offapi/com/sun/star/sdbc/XBlob.idl

   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  */
 111 published 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