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

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