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