Introduction

Ce tutoriel décrit la version orientée objet de l’API Firebird V4.0.+

Ce document est une traduction du fichier doc/Using_OO_API.html, qui est inclus dans les sources de Firebird.

Les interfaces décrites se trouvent dans le répertoire include/firebird/FirebirdInterface.idl. À l’aide de l’outil CLOOP sur la base de ce fichier IDL, vous pouvez générer un fichier d’interface pour un langage de programmation spécifique (IdlFbInterfaces.h ou Firebird.pas).

CLOOP — (Programmation orientée objet inter-langages). Cet outil n’est pas inclus dans Firebird. Il se trouve dans le code source de cloop.Une fois l’outil assemblé, vous pouvez générer une API pour votre langage de programmation.

Pour Object Pascal, le fichier API de l’objet est généré à l’aide de la commande suivante :

cloop FirebirdInterface.idl pascal Firebird.pas Firebird --uses SysUtils \
  --interfaceFile Pascal.interface.pas \
  --implementationFile Pascal.implementation.pas \
  --exceptionClass FbException --prefix I \
  --functionsFile fb_get_master_interface.pas

Les fichiers Pascal.interface.pas, Pascal.implementation.pas et fb_get_master_interface.pas se trouvent à l’adresse https://github.com/FirebirdSQL/firebird/tree/master/src/misc/pascal.

Note	Dans ce cas, les API Firebird seront préfixées par la lettre I, car c’est la coutume en Object Pascal.

Le fichier Firebird.pas qui en résulte ne contient pas les constantes isc_*. Ces constantes pour les langages C/C++ peuvent être trouvées à l’adressehttps://github.com/FirebirdSQL/firebird/tree/master/src/include/consts_pub.h.Pour obtenir les constantes en langage Pascal, utilisons un script AWK pour transformer la syntaxe. Sous Windows, vous devrez installer Gawk pour Windows ou utiliser le sous-système Windows pour Linux (disponible sur Windows 10). Pour ce faire, utilisez la commande suivante :

awk -f Pascal.Constants.awk consts_pub.h > const.pas

Le contenu du fichier résultant doit être copié dans la section const vide du fichier Firebird.pas immédiatement après l’implémentation. Le fichier Pascal.Constants.awk se trouve à l’adresse suivante : https://github.com/FirebirdSQL/firebird/tree/master/src/misc/pascal.

Firebird Interfaces

L’API orientée objet Firebird (API OO) est basée sur l’utilisation d’interfaces. Ces interfaces, bien qu’elles ressemblent à des interfaces OLE2 à certains égards (certaines d’entre elles ont des méthodes addRef() et release()), ne sont pas standard et ont des fonctionnalités que l’on ne trouve pas dans d’autres types d’interface couramment utilisés. Tout d’abord, les interfaces Firebird sont indépendantes du langage – ce qui signifie qu’elles n’ont pas besoin d’utiliser des constructions spécifiques au langage telles que class dans C++ pour les définir/utiliser, l’interface peut être définie en utilisant n’importe quel langage qui a le concept d’un tableau et d’un pointeur vers une procédure/fonction. De plus, les interfaces sont versionnées, ce qui signifie que nous prenons en charge différentes versions de la même interface. La disposition binaire des interfaces conçues pour prendre en charge ces fonctions est très efficace (il n’y a pas besoin d’appels virtuels supplémentaires comme dans OLE2/COM avec son QueryInterface), mais elle n’est pas pratique pour une utilisation directe dans la plupart des langages. Par conséquent, pour faciliter l’utilisation de l’API, il est préférable d’utiliser des wrappers spécifiques pour chaque différents langages. Nous avons actuellement des wrappers pour C++ et Pascal, Java arrive bientôt. Pour l’utilisateur final, il n’y a pas de différence entre les appels POV de C++ et Pascal, bien que Pascal n’ait pas certaines des fonctionnalités de langage présentes dans C++ (telles que la possibilité de désactiver la vérification automatique de l’état après les appels d’API) qui est absent en Pascal.

En règle générale, l’API OO est utilisée pour accéder aux données stockées dans la base de données. L’API Firebird OO accomplit certainement cette tâche, mais elle prend également en charge la création de vos propres plugins / UDRs – des modules qui vous permettent d’étendre les capacités de Firebird en fonction de vos besoins.C’est pourquoi ce document comporte deux grandes parties : l’accès aux bases de données et l’écriture de plugins. Bien sûr, certaines interfaces (par exemple le vecteur d’état) sont utilisées dans les deux parties de l’API, celles-ci seront discutées dans la partie accès aux données, et plus tard dans la discussion sur les plugins, nous nous y référerons librement. Donc, même si vous envisagez d’écrire une sorte de plugin, il est préférable de commencer par lire la première partie de ce document.De plus, de nombreux plugins eux-mêmes ont besoin d’accéder à des bases de données, ce qui nécessite généralement une API d’accès aux données.

Le paquet d’installation de Firebird contient un certain nombre d’exemples concrets d’utilisation de l’API OO, situés dans les répertoires examples/interfaces (accès à la base de données) et examples/dbcrypt (un plugin qui effectue un chiffrement factice de la base de données). Il est supposé que le lecteur soit familier avec l’API ISC utilisée dans Firebird depuis Interbase.

Ce document ne prétend pas être la documentation complete de Firebird – il décrit simplement l’API orientée objet, et le lecteur doit être familier avec les concepts de base de Firebird, la connaissance de l’API ISC est également un plus.Par exemple, lors de la description de l’utilisation des services, il n’y a pas d’explication de ce qu’est un service et de ce à quoi il sert, seulement une description de la façon d’obtenir l’interface IService et de la façon de l’utiliser. Notez également que les exemples de code ne tirent pas parti de la plupart des fonctionnalités puissantes de C++. Aucun pointeur de comptage de référence n’est utilisé, aucun modèle n’est utilisé (à l’exception de celui présent dans les en-têtes publics de Firebird), etc.L’objectif principal est de rendre ce texte applicable non seulement aux programmeurs C++ mais aussi à d’autres langages comme le Pascal.