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

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