mozIStorageStatement

Cette interface vous permet de créer et d'exécuter des instructions SQL sur une mozIStorageConnection.
Inherits from: mozIStorageValueArray Last changed in Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

Pour une introduction sur la façon d'utiliser cette interface, voir  document storage.

Aperçu des méthode

void initialize(in mozIStorageConnection aDBConnection, in AUTF8String aSQLStatement); Obsolète depuis Gecko 1.9.1
void finalize();
mozIStorageStatement clone();
AUTF8String getParameterName(in unsigned long aParamIndex);
unsigned long getParameterIndex(in AUTF8String aName);
AUTF8String getColumnName(in unsigned long aColumnIndex);
unsigned long getColumnIndex(in AUTF8String aName);
void reset();
AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar);
void bindParameters(in mozIStorageBindingParamsArray aParameters);
mozIStorageBindingParamsArray newBindingParamsArray();
void bindUTF8StringParameter(in unsigned long aParamIndex, in AUTF8String aValue);
void bindStringParameter(in unsigned long aParamIndex, in AString aValue);
void bindDoubleParameter(in unsigned long aParamIndex, in double aValue);
void bindInt32Parameter(in unsigned long aParamIndex, in long aValue);
void bindInt64Parameter(in unsigned long aParamIndex, in long long aValue);
void bindNullParameter(in unsigned long aParamIndex);
void bindBlobParameter(in unsigned long aParamIndex, [array,const,size_is(aValueSize)] in octet aValue, in unsigned long aValueSize);
mozIStoragePendingStatement executeAsync(mozIStorageStatementCallback aCallback);
boolean executeStep();
boolean step();
void execute();

Attributs

Attribute Type Description
columnCount unsigned long Nombre de colonnes retourné. Lecture seule.
parameterCount unsigned long Nombre de paramètres. Lecture seule.
params mozIStorageStatementParams La liste des paramètres nommés, qui peut être demandés. Disponible uniquement pour le code JavaScript. Lecture seule.
row mozIStorageStatementRow La ligne en cours, avec un accès à tous les données par leurs nom. Disponible uniquement au code JavaScript. Lecture seule.
state long L'état actuel défini par mozIStorageStatement.MOZ_STORAGE_STATEMENT_INVALID, mozIStorageStatement.MOZ_STORAGE_STATEMENT_READY ou mozIStorageStatement.MOZ_STORAGE_STATEMENT_EXECUTING . Lecture seule.

Statement status constants

Constant Value Description
MOZ_STORAGE_STATEMENT_INVALID 0 L'instruction SQL est non valide.
MOZ_STORAGE_STATEMENT_READY 1 L'instruction SQL est prêt à être exécuté.
MOZ_STORAGE_STATEMENT_EXECUTING 2 L'instruction SQL est en cours d'exécution.

Methods

initialize()

Obsolète depuis Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

Note :  Cette méthode a été supprimé pour Gecko 1.9.1. Pour initialiser une déclaration, les utilisateurs devraient appeler mozIStorageConnection.createStatement(). Cette méthode existe depuis Gecko 1.8.0.

Initialisation une requête avec l'instruction SQL donnée.

void initialize(
  in mozIStorageConnection aDBConnection, 
  in AUTF8String aSQLStatement
);
Paramètres
aDBConnection
Une mozIStorageConnection à une base de données.
aSQLStatement
Chaîne représentant l'instruction SQL.

finalize()

Finalise une déclaration qui libère toutes les ressources qui ont été allouées pour elle. Vous devez appeler cette méthode sur chaque instruction active avant d'appeler mozIStorageConnection.close().

void finalize();

Note : Cette méthode n'a pas besoin d'être utilisé par des utilisateurs locaux parce que vous devez libérer la déclaration avant d'arrêter. finalize sera appelé automatiquement lorsque le compteur de référence passe à zéro.

clone()

Crée une copie de la déclaration dont l'état sera mozIStorageStatement.MOZ_STORAGE_STATEMENT_READY.

mozIStorageStatement clone();
Valeur de retour

mozIStorageStatement est une copie de l'instruction en cours.

getParameterName()

Obtient le nom du paramètre pour l'index spécifié.

AUTF8String getParameterName(
  in unsigned long aParamIndex
);
Paramètres
aParamIndex

L'index numérique de base zéro pour le paramètre appelé. Ce sera n-1 par rapport au nombre utilisé dans SQL (<code>?1</code> pour <code>0</code>,  et ainsi de suite).

Valeur de retour

Un AUTF8String représentant le nom de paramètre pour l'index spécifié.

getParameterIndex()

Obtient l'index du paramètre avec le nom spécifié. Cette méthode a été ajoutée en 1.9.0. En 1.8.1, il fallait utiliser getParameterIndexes(). Voir bug 388048 pour plus de détails.

unsigned long getParameterIndex(
  in AUTF8String aName
);
Paramètres
aName
Nom du paramètre pour obtenir l'index. Pour le paramètre 'foo', le format de nom est ':foo' dans 1.9.0 et 1.9.1. dans 1.9.2 le ':' a été abandonnée et la valeur du nom doit être juste 'foo'. Voir bug 528166 pour plus de détails.
Valeur de retour

L'index numérique de base zéro pour le paramètre appelé. Ce sera n-1 par rapport au nombre utilisé dans SQL (<code>?1</code> pour <code>0</code>,  et ainsi de suite).

getColumnName()

Obtient le nom de la colonne pour l'index spécifié.

AUTF8String getColumnName(
  in unsigned long aColumnIndex
);
Paramètres
aColumnIndex

L'indice numérique de base zéro de la colonne.

Valeur de retour

Un AUTF8String avec le du nom de la colonne pour l'index spécifié.

getColumnIndex()

Obtient l'index de la colonne avec le nom spécifié.

unsigned long getColumnIndex(
  in AUTF8String aName
);
Paramètres
aName
Le nom de la colonne.
Return value

L'indice numérique de base zéro de la colonne.

reset()

Réinitialise les paramètres liés et l'état d'exécution de l'instruction. Doit être appelé avant de réutiliser la déclaration.

Note : Les utilisateurs JavaScript doivent toujours envelopper leur exécution dans un bloc try, et une déclaration de remise à zéro dans un bloc finally.

Voir le document de synthèse sur le stockag pour plus de détails.

void reset()

escapeStringForLIKE()

Entre une chaîne pour une recherche SQL LIKE.

Note : Les utilisateurs devront utiliser le même caractère d'échappement lorsque ils font des déclarations telles que: ...LIKE '?1' ESCAPE '/'.... Voir l'exemple de code pour plus de détails.

AString escapeStringForLIKE(
  in AString aValue, 
  in wchar aEscapeChar
);
Paramètres
aValue
Chaîne d'enter pour SQL LIKE.
aEscapeChar
Le caractère d'échappement à utiliser. En général "/ " sera suffisant.
Valeur de retour

Une chaîne encodée UTF-16 qui a des caractères qui ont une signification particulière pour aValue.

Sample Code
var statement = dbConn.createStatement(
  "SELECT * " +
  "FROM table_name " +
  "WHERE column_name LIKE :userInput ESCAPE '/'"
);
statement.params.userInput = statement.escapeStringForLIKE(someUserInput, "/");

Fonctions de liaison

Ces fonctions sont discutés plus en détail avec exemple de code dans Storage.

newBindingParamsArray()

Crée et retourne un nouvel mozIStorageBindingParamsArray objet qui peut être utilisé pour lier des valeurs multiples à des paramètres en cours de préparation pour appeler executeAsync().

mozIStorageBindingParamsArray newBindingParamsArray();
Paramètres

Aucun.

bindParameters()

Relie tous les paramètres dans un tableau spécifié à la déclaration en préparation pour appeler executeAsync().

Remarque: À partir de Gecko 2.0, cette méthode renvoie NS_ERROR_UNEXPECTED si mozIStorageBindingParamsArray est vide .
void bindParameters(
  in mozIStorageBindingParamsArray aParameters
); 
Paramètres
aParameters
L'objet mozIStorageBindingParamsArray contenant un ou plusieurs objets mozIStorageBindingParams contenant les paramètres liés à la déclaration avant l'exécution.

bindUTF8StringParameter()

Associe un UTF8String à l'index spécifié.

void bindUTF8StringParameter(
  in unsigned long aParamIndex, 
  in AUTF8String aValue
);
Paramètres
aParamIndex
L'index numérique de base zéro pour le paramètre appelé. Ce sera n-1 par rapport au nombre utilisé dans SQL (<code>?1</code> pour <code>0</code>,  et ainsi de suite).
aValue
Valeur lié à l'index spécifié.

bindStringParameter()

Associe un paramètre de chaîne à l'index spécifié.

void bindStringParameter(
  in unsigned long aParamIndex, 
  in AString aValue
);
paramêtres
aParamIndex
L'index numérique de base zéro pour le paramètre appelé. Ce sera n-1 par rapport au nombre utilisé dans SQL (<code>?1</code> pour <code>0</code>,  et ainsi de suite).
aValue
Valeur lié à l'index spécifié.

bindDoubleParameter()

Relie un réel double à l'index spécifié.

void bindDoubleParameter(
  in unsigned long aParamIndex, 
  in double aValue
);
Paramètres
aParamIndex
L'index numérique de base zéro pour le paramètre appelé. Ce sera n-1 par rapport au nombre utilisé dans SQL (<code>?1</code> pour <code>0</code>,  et ainsi de suite).
aValue
Valeur lié à l'index spécifié.

bindInt32Parameter()

Associe un Int32 à l'index spécifié.

void bindInt32Parameter(
  in unsigned long aParamIndex, 
  in long aValue
);
Paramètres
aParamIndex
L'index numérique de base zéro pour le paramètre appelé. Ce sera n-1 par rapport au nombre utilisé dans SQL (<code>?1</code> pour <code>0</code>,  et ainsi de suite).
aValue
Valeur lié à l'index spécifié.

bindInt64Parameter()

Associe un Int64 à l'index spécifié.

void bindInt64Parameter(
  in unsigned long aParamIndex, 
  in long long aValue
);
Paramètres
aParamIndex
L'index numérique de base zéro pour le paramètre appelé. Ce sera n-1 par rapport au nombre utilisé dans SQL (<code>?1</code> pour <code>0</code>,  et ainsi de suite).
aValue
Valeur lié à l'index spécifié.

bindNullParameter()

Associe un paramètre null à l'index spécifié.

void bindNullParameter(
  in unsigned long aParamIndex
);
Paramètres
aParamIndex
L'index numérique de base zéro pour le paramètre appelé. Ce sera n-1 par rapport au nombre utilisé dans SQL (<code>?1</code> pour <code>0</code>,  et ainsi de suite).

bindBlobParameter()

Associe un paramètre blob à l'index spécifié.

void bindBlobParameter(
  in unsigned long aParamIndex, 
  [array,const,size_is(aValueSize)] in octet aValue, 
  in unsigned long aValueSize
);
Parameters
aParamIndex
L'index numérique de base zéro pour le paramètre appelé. Ce sera n-1 par rapport au nombre utilisé dans SQL (<code>?1</code> pour <code>0</code>,  et ainsi de suite).
aValue
Valeur lié à l'index spécifié.
aValueSize
Taille de aValue.

Fonctions d'exécution

Ces fonctions sont discutés plus en détail avec exemple de code dans overview document.

executeAsync()

Démarre l'exécution d'une requête asynchrone avec les paramètres liés. La routine de rappel facultative reçoit des notifications sur l'état d'avancement de la requête. Pour des exemples de code et plus de détails, voir Storage .

Note : La déclaration n'a pas à être remis à zéro avant d'être réutilisés.

mozIStoragePendingStatement executeAsync(
  [optional] mozIStorageStatementCallback aCallback
);
Paramètres
aCallback
Un objet de rappel qui sera informé des progrès, des erreurs, et de la fin de la requête. Ce paramètre est facultatif.
Valeur de retour

Un objet mozIStoragePendingStatement qui peut être utilisé pour annuler l'exécution de l'instruction.

executeStep()

Avertissement : Performing synchronous IO on the main thread can cause serious performance problems. As a result, using this method on the main thread is strongly discouraged!

Exécute une requête synchrone avec les paramètres liés, et donne les résultats ligne par ligne. Pour des exemples de code et plus de détails, voir le Storage .

Note : La déclaration doit être remise à zéro avant d'être réutilisés.

boolean executeStep();
Valeur de retour

Retourne un boolean indiquant s'il y a encor des lignes ou pas. les données par ligne peuvent être accessibles en utilisant la méthodes mozIStorageValueArray avec la déclaration.

step()

Identique un appelle executeStep(), puis un appelle reset() quand il n'y a plus de ligne à retourner.

Note: Cette méthode ne peut être appelée à partir du code JavaScript .
boolean step()
Valeur de retour

true s'il y a encor des lignes disponible dans les résultats, sinon false.

execute()

Avertissement : Performing synchronous IO on the main thread can cause serious performance problems. As a result, using this method on the main thread is strongly discouraged!

Exécutez la requête, sans tenir compte des résultats. Ceci est accompli en appelant executeStep(), puis reset().

 void execute();

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : jmh
 Dernière mise à jour par : jmh,