storage/mozIStorageBindingParams.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: sw=2 ts=2 sts=2 et
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8
   9 interface nsIVariant;
  10
  11 [ptr] native octetPtr(uint8_t);
  12
  13 [scriptable, builtinclass, uuid(2d09f42f-966e-4663-b4b3-b0c8676bf2bf)]
  14 interface mozIStorageBindingParams : nsISupports {
  15   /**
  16    * Binds aValue to the parameter with the name aName.
  17    *
  18    * @param aName
  19    *        The name of the parameter to bind aValue to.
  20    * @param aValue
  21    *        The value to bind.
  22    * @warning To bind an array use a specific `bindArrayOf` method instead.
  23    */
  24    void bindByName(in AUTF8String aName,
  25                    in nsIVariant aValue);
  26    [noscript] void bindUTF8StringByName(in AUTF8String aName,
  27                                         in AUTF8String aValue);
  28    [noscript] void bindStringByName(in AUTF8String aName,
  29                                     in AString aValue);
  30    [noscript] void bindDoubleByName(in AUTF8String aName,
  31                                     in double aValue);
  32    [noscript] void bindInt32ByName(in AUTF8String aName,
  33                                    in long aValue);
  34    [noscript] void bindInt64ByName(in AUTF8String aName,
  35                                    in long long aValue);
  36    [noscript] void bindNullByName(in AUTF8String aName);
  37
  38    // The noscript version of bindBlobByName can be used with any (const
  39    // uint8_t*, length) pair.  The scriptable version is meant for use with
  40    // nsTArray<uint8_t>, which is what xpconnect has to work with.
  41    [noscript, binaryname(BindBlobByName)]
  42    void bindBlobByNameNoscript(in AUTF8String aName,
  43                                [const] in octetPtr aValue,
  44                                in unsigned long aValueSize);
  45    [binaryname(BindBlobArrayByName)]
  46    void bindBlobByName(in AUTF8String aName, in Array<octet> aValue);
  47
  48    // Convenience routines for storing strings as blobs.
  49    void bindStringAsBlobByName(in AUTF8String aName, in AString aValue);
  50    void bindUTF8StringAsBlobByName(in AUTF8String aName, in AUTF8String aValue);
  51
  52    // The function adopts the storage for the provided blob.  After calling
  53    // this function, mozStorage will ensure that free is called on the
  54    // underlying pointer.
  55    [noscript]
  56    void bindAdoptedBlobByName(in AUTF8String aName,
  57                               in octetPtr aValue,
  58                               in unsigned long aValueSize);
  59
  60    // These allow to bind arrays through the carray() tabled-valued function,
  61    // thus they should only be used when the query contains `carray(?N)`.
  62    void bindArrayOfIntegersByName(in AUTF8String aName,
  63                                   in Array<int64_t> aValue);
  64    void bindArrayOfDoublesByName(in AUTF8String aName,
  65                                  in Array<double> aValue);
  66    void bindArrayOfStringsByName(in AUTF8String aName,
  67                                  in Array<AString> aValue);
  68    void bindArrayOfUTF8StringsByName(in AUTF8String aName,
  69                                      in Array<AUTF8String> aValue);
  70
  71    /**
  72     * Binds aValue to the parameter with the index aIndex.
  73     *
  74     * @param aIndex
  75     *        The zero-based index of the parameter to bind aValue to.
  76     * @param aValue
  77     *        The value to bind.
  78     * @warning To bind an array use a specific `bindArrayOf` method instead.
  79     */
  80    void bindByIndex(in unsigned long aIndex,
  81                     in nsIVariant aValue);
  82    [noscript] void bindUTF8StringByIndex(in unsigned long aIndex,
  83                                          in AUTF8String aValue);
  84    [noscript] void bindStringByIndex(in unsigned long aIndex,
  85                                      in AString aValue);
  86    [noscript] void bindDoubleByIndex(in unsigned long aIndex,
  87                                      in double aValue);
  88    [noscript] void bindInt32ByIndex(in unsigned long aIndex,
  89                                     in long aValue);
  90    [noscript] void bindInt64ByIndex(in unsigned long aIndex,
  91                                     in long long aValue);
  92    [noscript] void bindNullByIndex(in unsigned long aIndex);
  93
  94    // The noscript version of bindBlobByIndex can be used with any (const
  95    // uint8_t*, length) pair.  The scriptable version is meant for use with
  96    // nsTArray<uint8_t>, which is what xpconnect has to work with.
  97    [noscript, binaryname(BindBlobByIndex)]
  98    void bindBlobByIndexNoscript(in unsigned long aIndex,
  99                                 [const] in octetPtr aValue,
 100                                 in unsigned long aValueSize);
 101    [binaryname(BindBlobArrayByIndex)]
 102    void bindBlobByIndex(in unsigned long aIndex,
 103                         in Array<octet> aValue);
 104
 105    // Convenience routines for storing strings as blobs.
 106    void bindStringAsBlobByIndex(in unsigned long aIndex, in AString aValue);
 107    void bindUTF8StringAsBlobByIndex(in unsigned long aIndex, in AUTF8String aValue);
 108
 109    // The function adopts the storage for the provided blob.  After calling
 110    // this function, mozStorage will ensure that free is called on the
 111    // underlying pointer.
 112    [noscript]
 113    void bindAdoptedBlobByIndex(in unsigned long aIndex,
 114                                in octetPtr aValue,
 115                                in unsigned long aValueSize);
 116
 117    // These allow to bind arrays through the carray() tabled-valued function,
 118    // thus they should only be used when the query contains `carray(?N)`.
 119    void bindArrayOfIntegersByIndex(in unsigned long aIndex,
 120                                    in Array<int64_t> aValue);
 121    void bindArrayOfDoublesByIndex(in unsigned long aIndex,
 122                                   in Array<double> aValue);
 123    void bindArrayOfStringsByIndex(in unsigned long aIndex,
 124                                   in Array<AString> aValue);
 125    void bindArrayOfUTF8StringsByIndex(in unsigned long aIndex,
 126                                       in Array<AUTF8String> aValue);
 127 };