xref: /trunk/main/offapi/com/sun/star/sdbc/XBlob.idl (revision d1766043)
1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_sdbc_XBlob_idl__
24#define __com_sun_star_sdbc_XBlob_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30 module com {  module sun {  module star {  module io {
31 published interface XInputStream;
32};};};};
33
34#ifndef __com_sun_star_sdbc_SQLException_idl__
35#include <com/sun/star/sdbc/SQLException.idl>
36#endif
37
38 module com {  module sun {  module star {  module sdbc {
39
40
41/** is the representation (mapping) of an SQL
42	<i>
43	BLOB
44	</i>
45	.
46
47	<p>
48	A SQL
49	<i>
50	BLOB
51	</i>
52	is a built-in type that stores a
53	Binary Large Object as a column value in a row of a database table.
54	The driver implements
55	<i>
56	BLOB
57	</i>
58	using a
59	SQL
60	<code>locator(BLOB)</code>
61	, which means that a
62	<code>Blob</code>
63	object contains a logical pointer to the SQL
64	<i>
65	BLOB
66	</i>
67	data rather than the data itself.
68	<br/>
69	A
70	<code>Blob</code>
71	object is valid for the duration of the transaction in which is was created.
72
73	</p>
74	<p>
75	Methods in the interfaces
76	<type scope="com::sun::star::sdbc">XResultSet</type>
77	,
78	and
79	<type scope="com::sun::star::sdbc">XPreparedStatement</type>
80	, such as
81	<code>getBlob</code>
82	and
83	<code>setBlob</code>
84	allow a programmer to access the SQL
85	<i>
86	BLOB
87	</i>
88	.
89	<br/>
90	The
91	<code>Blob</code>
92	interface provides methods for getting the length of a SQL
93	<i>
94	BLOB
95	</i>
96	(Binary Large Object) value, for materializing a
97	<i>
98	BLOB
99	</i>
100	value on the client and for determining the position of a pattern of bytes within a
101	<i>
102	BLOB
103	</i>
104	value.
105	</p>
106 */
107published interface XBlob: com::sun::star::uno::XInterface
108{
109	//-------------------------------------------------------------------------
110
111	/** returns the number of bytes in the
112		<i>
113		BLOB
114		</i>
115		value
116		designated by this
117		<code>Blob</code>
118		object.
119		@returns
120			the length
121		@throws SQLException
122			if a database access error occurs.
123	 */
124	hyper length() raises (SQLException);
125
126  	//-------------------------------------------------------------------------
127
128	/** returns as an array of bytes part or all of the
129			<i>
130			BLOB
131			</i>
132		     value that this
133			 <code>Blob</code>
134			 object designates.  The byte
135		     array contains up to
136			 <code>length</code>
137			 consecutive bytes
138		     starting at position
139			 <code>pos</code>.
140		     @param pos
141				is the ordinal position of the first byte in the
142		   	 	<i>
143				BLOB
144				</i>
145				value to be extracted; the first byte is at
146		   	 	position 1.
147		     @param length
148				is the number of consecutive bytes to be copied.
149		     @returns
150				a byte array containing up to
151				<code>length</code>
152		   	 	consecutive bytes from the
153				<i>
154				BLOB
155				</i>
156				value designated
157		     	by this
158				<code>Blob</code>
159				object, starting with the byte at position
160				<code>pos</code>
161				.
162			 @throws SQLException
163				if there is an error accessing the
164				<i>
165				BLOB
166				</i>
167				.
168	 */
169	sequence<byte> getBytes([in]hyper pos, [in]long length)
170		raises (SQLException);
171
172  	//-------------------------------------------------------------------------
173
174	/** retrieves the
175		<i>
176		BLOB
177		</i>
178		designated by this
179		<code>Blob</code>
180		instance as a stream.
181		@returns
182			the stream
183		@throws SQLException
184			if a database access error occurs.
185	 */
186	com::sun::star::io::XInputStream getBinaryStream()
187		raises (SQLException);
188  	//-------------------------------------------------------------------------
189
190	/** determines the byte position at which the specified byte
191		<code>pattern</code>
192		begins within the
193		<i>
194		BLOB
195		</i>
196		value that this
197		<code>Blob</code>
198		object represents.  The
199		search for
200		<code>pattern</code>
201		begins at position
202		<code>start</code>
203		.
204		@param pattern
205			the pattern to search
206		@returns
207			the position
208		@throws SQLException
209			if a database access error occurs.
210	 */
211	hyper position([in]sequence<byte> pattern, [in]hyper start)
212		raises (SQLException);
213
214  	//-------------------------------------------------------------------------
215
216	/** determines the byte position in the
217		<i>
218		BLOB
219		</i>
220		value
221		designated by this
222		<code>Blob</code>
223		object at which
224		<code>pattern</code>
225		begins. The search begins at position
226		<code>start</code>
227		.
228		@param pattern
229			the pattern to search
230		@param start
231			position to start
232		@returns
233			the position
234		@throws SQLException
235			if a database access error occurs.
236	 */
237	hyper positionOfBlob([in]XBlob pattern,[in] hyper start)
238	 	raises (SQLException);
239};
240
241//=============================================================================
242
243}; }; }; };
244
245/*===========================================================================
246===========================================================================*/
247#endif
248