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
  20  module com {  module sun {  module star {  module io {
  21  published interface XInputStream;
  22 };};};};
  23
  24  module com {  module sun {  module star {  module sdbc {
  25
  26
  27 /** is the representation (mapping) of an SQL <i>BLOB</i>.
  28
  29     <p>
  30     A SQL
  31     <i>
  32     BLOB
  33     </i>
  34     is a built-in type that stores a
  35     Binary Large Object as a column value in a row of a database table.
  36     The driver implements
  37     <i>
  38     BLOB
  39     </i>
  40     using a
  41     SQL
  42     <code>locator(BLOB)</code>
  43     , which means that a
  44     <code>Blob</code>
  45     object contains a logical pointer to the SQL
  46     <i>
  47     BLOB
  48     </i>
  49     data rather than the data itself.
  50     <br/>
  51     A
  52     <code>Blob</code>
  53     object is valid for the duration of the transaction in which is was created.
  54
  55     </p>
  56     <p>
  57     Methods in the interfaces
  58     com::sun::star::sdbc::XResultSet
  59     ,
  60     and
  61     com::sun::star::sdbc::XPreparedStatement
  62     , such as
  63     <code>getBlob</code>
  64     and
  65     <code>setBlob</code>
  66     allow a programmer to access the SQL
  67     <i>BLOB</i>.
  68     <br/>
  69     The
  70     <code>Blob</code>
  71     interface provides methods for getting the length of a SQL
  72     <i>
  73     BLOB
  74     </i>
  75     (Binary Large Object) value, for materializing a
  76     <i>
  77     BLOB
  78     </i>
  79     value on the client and for determining the position of a pattern of bytes within a
  80     <i>
  81     BLOB
  82     </i>
  83     value.
  84     </p>
  85  */
  86 published interface XBlob: com::sun::star::uno::XInterface
  87 {
  88
  89     /** returns the number of bytes in the
  90         <i>
  91         BLOB
  92         </i>
  93         value
  94         designated by this
  95         <code>Blob</code>
  96         object.
  97         @returns
  98             the length
  99         @throws SQLException
 100             if a database access error occurs.
 101      */
 102     hyper length() raises (SQLException);
 103
 104
 105     /** returns as an array of bytes part or all of the
 106             <i>
 107             BLOB
 108             </i>
 109              value that this
 110              <code>Blob</code>
 111              object designates.  The byte
 112              array contains up to
 113              <code>length</code>
 114              consecutive bytes
 115              starting at position
 116              <code>pos</code>.
 117              @param pos
 118                 is the ordinal position of the first byte in the
 119                     <i>
 120                 BLOB
 121                 </i>
 122                 value to be extracted; the first byte is at
 123                     position 1.
 124              @param length
 125                 is the number of consecutive bytes to be copied.
 126              @returns
 127                 a byte array containing up to
 128                 <code>length</code>
 129                     consecutive bytes from the
 130                 <i>
 131                 BLOB
 132                 </i>
 133                 value designated
 134                  by this
 135                 <code>Blob</code>
 136                 object, starting with the byte at position
 137                 <code>pos</code>.
 138              @throws SQLException
 139                 if there is an error accessing the <i>BLOB</i>.
 140      */
 141     sequence<byte> getBytes([in]hyper pos, [in]long length)
 142         raises (SQLException);
 143
 144
 145     /** retrieves the
 146         <i>
 147         BLOB
 148         </i>
 149         designated by this
 150         <code>Blob</code>
 151         instance as a stream.
 152         @returns
 153             the stream
 154         @throws SQLException
 155             if a database access error occurs.
 156      */
 157     com::sun::star::io::XInputStream getBinaryStream()
 158         raises (SQLException);
 159
 160     /** determines the byte position at which the specified byte
 161         <code>pattern</code>
 162         begins within the
 163         <i>
 164         BLOB
 165         </i>
 166         value that this
 167         <code>Blob</code>
 168         object represents.  The
 169         search for
 170         <code>pattern</code>
 171         begins at position <code>start</code>.
 172
 173         @param pattern
 174             the pattern to search
 175         @param start
 176             the start position for the search
 177         @returns
 178             the position
 179         @throws SQLException
 180             if a database access error occurs.
 181      */
 182     hyper position([in]sequence<byte> pattern, [in]hyper start)
 183         raises (SQLException);
 184
 185
 186     /** determines the byte position in the
 187         <i>
 188         BLOB
 189         </i>
 190         value
 191         designated by this
 192         <code>Blob</code>
 193         object at which
 194         <code>pattern</code>
 195         begins. The search begins at position <code>start</code>.
 196         @param pattern
 197             the pattern to search
 198         @param start
 199             position to start
 200         @returns
 201             the position
 202         @throws SQLException
 203             if a database access error occurs.
 204      */
 205     hyper positionOfBlob([in]XBlob pattern,[in] hyper start)
 206          raises (SQLException);
 207 };
 208
 209
 210 }; }; }; };
 211
 212 /*===========================================================================
 213 ===========================================================================*/
 214
 215 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */