Il existe deux façons d’exécuter une instruction avec des paramètres d’entrée.Le choix de la bonne méthode dépend du fait que vous deviez l’exécuter plus d’une fois et que vous connaissiez ou non le format des paramètres au préalable. Lorsque ce format est connu et que vous n’avez besoin d’exécuter l’instruction qu’une seule fois, vous pouvez utiliser un seul appel à IAttachment::execute(). Sinon, vous devez d’abord préparer une requête SQL, puis vous pouvez l’exécuter à plusieurs reprises avec différents paramètres.

Pour préparer une instruction SQL en vue de son exécution, utilisez la méthode prepare() de l’interface IAttachment :

Si vous n’avez pas l’intention d’utiliser la description des paramètres de Firebird (c’est-à-dire que vous pouvez fournir cette information vous-même), utilisez IStatement::PREPARE_PREFETCH_NONE au lieu de IStatement::PREPARE_PREFETCH_METADATA – cela réduira légèrement le trafic client/serveur et économisera des ressources.

Dans l’API ISC, la structure XSQLDA est utilisée pour décrire le format des paramètres de l’opérateur. La nouvelle API n’utilise pas XSQLDA — elle utilise IMessageMetadata à la place.Un ensemble de paramètres d’entrée (ainsi qu’un enregistrement extrait du curseur) est décrit dans l’API Firebird de la même manière, ci-après dénommé message.IMessageMetadata est transmis en tant que paramètre aux méthodes de messagerie entre le programme et le moteur de base de données. Il existe de nombreuses façons d’obtenir une instance de IMessageMetadata, en voici quelques-unes :

La récupération des métadonnées à partir d’une requête préparée est très simple : la méthode getInputMetadata() renvoie une interface qui décrit le message d’entrée (c’est-à-dire les paramètres de l’opérateur), l’interface renvoyée par getOutputMetadata() décrit le message de sortie (c’est-à-dire une chaîne de données ou de valeurs sélectionnées renvoyées par la procédure). Dans notre cas, nous pouvons faire ce qui suit :

Ou nous pouvons créer nous-mêmes le message de métadonnées. Pour ce faire, tout d’abord, nous devons obtenir l’interface du constructeur :

Le deuxième paramètre est le nombre attendu de champs dans le message, il peut être modifié ultérieurement, c’est-à-dire qu’il n’est nécessaire que pour l’optimisation.

Ensuite, vous devez définir les caractéristiques individuelles des champs dans le générateur. Les types et longueurs de champ minimum requis sont les suivants :

La nouvelle API utilise les anciennes constantes pour les types SQL, le plus petit bit est toujours utilisé pour indiquer la possibilité de prendre une valeur null. Dans certains cas, il est judicieux de définir un sous-type (pour les BLOB), un jeu de caractères (pour les zones de texte) ou un facteur d’échelle (pour les champs numériques).Enfin, il est temps d’obtenir une instance de IMessageMetadata :

Nous ne discutons pas ici de notre propre implémentation de IMessageMetadata. Si cela vous intéresse, vous pouvez consulter l’exemple de 05.user_metadata.cpp.

Nous avons donc une instance de la description des métadonnées des paramètres d’entrée. Mais pour travailler avec le message, nous avons aussi besoin d’un tampon. La taille de la mémoire tampon est l’une des principales caractéristiques des messages de métadonnées et est renvoyée par la méthode getMessageLength() de IMessageMetadata :

Afin de traiter les valeurs individuelles à l’intérieur du tampon, le décalage par rapport à celles-ci doit être pris en compte. IMessageMetadata renseigne les décalages pour toutes les valeurs du message, en l’utilisant, nous pouvons créer des pointeurs vers celles-ci :

N’oubliez pas non plus de traiter les flags NULL :

Une fois les manipulations de décalage terminées, nous sommes prêts à obtenir les valeurs des paramètres :

et exécutez l’instruction préparée :

Les deux derniers paramètres NULL sont pour les messages de sortie et sont généralement utilisés pour l’instruction EXECUTE PROCEDURE.

Si vous n’avez pas besoin de récupérer les métadonnées de l’instruction et que vous prévoyez de ne l’exécuter qu’une seule fois, vous pouvez choisir une méthode plus simple — utilisez la méthode execute() de l’interface IAttachment :

Dans ce cas, vous n’avez pas du tout besoin d’utiliser IStatement.

Un exemple d’exécution de l’instruction UPDATE avec des paramètres est présent dans 02.update.cpp ou l’exemple en Pascal 02.update.pas, vous verrez également comment une exception levée dans un déclencheur / procédure peut être interceptée dans un programme C++ ou Pascal.

La seule façon d’obtenir les lignes de données renvoyées par l’instruction SELECT dans l’API OO est d’utiliser IResultSet. Cette interface est retournée par la méthode openCursor() accessible à la fois dans IAttachment et IStatement. openCursor() est similaire à execute() dans la plupart des aspects, et décider comment ouvrir le curseur (en utilisant une instruction préparée ou directement à partir de l’interface de connexion) est la même chose. Les exemples 03.select.cpp version en Pascal 03.select.pas et 04.print_table.cpp utilisent les deux approches.Notez qu’une différence entre la méthode openCursor() et la méthode execute() est que rien n’est passé au tampon pour le message de sortie à openCursor(), il sera passé plus tard lorsque les données seront récupérées à partir du curseur. Cela vous permet d’ouvrir un curseur avec un format de message de sortie inconnu (NULL est passé à la place des métadonnées de sortie). Dans ce cas, Firebird utilise le format de message par défaut, qui peut être interrogé via l’interface IResultSet :

Par la suite, ces métadonnées peuvent être utilisées pour allouer une mémoire tampon aux données et analyser les lignes extraites.

Vous pouvez également préparer l’instruction, récupérer les métadonnées à partir de l’instruction préparée, puis ouvrir le curseur. Il s’agit de la méthode à privilégier si vous vous attendez à ce que le curseur soit ouvert plus d’une fois.

Nous avons obtenu (d’une manière ou d’une autre) une instance de la description des métadonnées des champs de sortie (lignes dans le jeu de données). Pour travailler avec le message, nous avons également besoin d’un tampon :

Il existe de nombreuses méthodes de récupération différentes dans l’interface IResultSet, mais lorsque le curseur n’est pas ouvert avec l’option SCROLL, seule fetchNext() fonctionne, c’est-à-dire que vous ne pouvez avancer que dans les enregistrements suivant. En plus des erreurs et des avertissements dans l’état, la méthode fetchNext() renvoie un code de complétion qui est RESULT_OK (lorsque le tampon est rempli avec des valeurs pour la ligne suivante) ou RESULT_NO_DATA (lorsqu’il n’y a plus de lignes après le curseur). RESULT_NO_DATA n’est pas un état d’erreur, c’est un état normal une fois la méthode terminée, qui signale qu’il n’y a plus de données dans le curseur. Si un wrapper d’état est utilisé, aucune exception n’est levée si une erreur est renvoyée.Une autre valeur, RESULT_ERROR, peut être renvoyée, ce qui signifie qu’il n’y a pas de données dans le tampon et des erreurs dans l’état du vecteur. La méthode fetchNext() est généralement appelée dans une boucle :

Ce qui se passe lorsque les enregistrements sont traitées dépend de vos besoins.Pour accéder à un champ spécifique, utilisez le décalage du champ :

où n est le numéro du champ dans le message. Ce pointeur doit être affecté au type approprié, en fonction du type de champ. Par exemple, pour le champ VARCHAR, vous devez utiliser le cast dans la structure vary :

Nous pouvons maintenant afficher la valeur du champ :

Si vous voulez obtenir les meilleures performances, il est utile de mettre en cache les valeurs de métadonnées dont vous avez besoin, comme nous le faisons dans nos exemples 03.select.cpp version en Pascal 03.select.pas et 04.print_table.cpp .

Travailler avec des données à l’aide de décalages de champs est assez efficace, mais cela nécessite beaucoup de code. Dans C++, ce problème peut être résolu avec des modèles, mais même par rapport à eux, la façon la plus pratique de travailler avec un message est de le présenter sous sa forme native : une structure en C/C++, un record en Pascal, etc.Bien entendu, cela ne fonctionne que si le format du message est connu à l’avance. Pour créer de telles structures en C++ dans Firebird, il y a une macro spéciale FB_MESSAGE.

FB_MESSAGE a 3 arguments : le nom du message (structure), le type d’enveloppe d’état et la liste des champs. L’utilisation du premier et du deuxième argument est évidente, la liste des champs contient des paires (field_type, field_name), où field_type est l’un des suivants :

Dans la structure générée par le préprocesseur, les types integer et float sont mappés aux types C correspondants, les types date et time sont mappés aux classes FbDate et FbTime (toutes les classes mentionnées ici sont dans l’espace de noms Firebird), le type timestamp est mappé à la classe FbTimestamp, qui contient deux membres de données publiques, la date et l’heure des classes respectives, et le type char est mappé à la structure du lien : #fbapi-objects-fbchar[FbChar] et varchar — avec la structure FbVarChar. Pour chaque champ, le préprocesseur crée deux membres de données : name pour la valeur du champ/paramètre et nameNull pour l’indicateur NULL. Le constructeur de message a 2 paramètres : un pointeur vers le wrapper d’état et une interface maître :

Pour les messages statiques, l’utilisation de FB_MESSAGE est le meilleur choix, mais ils peuvent facilement être passés aux méthodes execute, openCursor et fetch :

et est utilisé pour travailler avec les valeurs des champs individuels :

Pour obtenir un exemple d’utilisation de la macro FB_MESSAGE pour travailler avec des messages, consultez l’exemple 06.fb_message.cpp.

Pour les blobs, Firebird stocke un identifiant BLOB dans le tampon de message, qui est un objet de 8 octets qui doit être aligné sur une limite de 4 octets. L’identifiant est de type ISC_QUAD. L’interface IAttachment a 2 méthodes pour travailler avec les BLOBs, openBlob() et createBlob(), qui renvoient l’interface IBlob et ont le même ensemble de paramètres, mais effectuent des actions légèrement différentes : openBlob() prend l’ID BLOB du message et prépare le BLOB pour la lecture, et createBlob() crée un nouveau BLOB, met son identifiant dans le message et prépare le BLOB pour l’écriture.

Pour travailler avec des BLOB, vous devez d`abord inclure leurs identifiants BLOB dans le message. Si vous obtenez des métadonnées d`un champ du moteur Firebird du type approprié, cet identifiant sera déjà présent. Dans ce cas, vous utilisez simplement son offset (à condition que la variable blobFieldNumber contienne le numéro du champ BLOB) (et l`offset NULL correspondant pour vérifier NULL ou mettre le flag NULL) pour obtenir le pointeur dans le tampon du message :

Si vous utilisez les messages de macro statiques FB_MESSAGE, le champ BLOB sera déclaré comme étant de type FB_BLOB :

Pour créer un nouveau BLOB, appelez la méthode createBlob() :

Les deux dernières options ne sont requises que si vous souhaitez utiliser des filtres d’objets blob ou un flux d’objets blob, qui ne sont pas abordés ici.

L’interface Blob est maintenant prête à accepter des données dans le BLOB. Utilisez la méthode putSegment() pour envoyer des données au moteur :

Après avoir envoyé des données au BLOB, n`oubliez pas de fermer l`interface du BLOB :

Assurez-vous que l’indicateur null n’est pas défini (non requis si vous avez vidé l’intégralité de la mémoire tampon de message avant de créer le BLOB) :

et un message qui contient un objet BLOB peut être utilisé dans une instruction d’insertion ou de mise à jour. Une fois cette instruction exécutée, le nouvel objet blob est stocké dans la base de données.

Pour lire un blob, vous devez obtenir son identifiant dans un message du noyau firebird. Cela peut être fait en utilisant les méthodes fetch() ou execute(). Après cela, utilisez la méthode openBlob() :

L’interface Blob est prête à fournir des données BLOB. Utilisez la méthode getSegment() pour obtenir les données du moteur :

Le dernier paramètre de userFunctionAcceptingBlobData() est l’indicateur de fin de segment — lorsque getSegment() renvoie le code de complétion RESULT_SEGMENT, qui sera notifié à la fonction (le dernier paramètre est passé false), c’est-à-dire que ce segment n’est pas lu complètement, et la suite est attendue lors de l’appel suivant.

Lorsque vous avez terminé avec le BLOB, n’oubliez pas de le fermer :

Étant donné que Firebird 4.0 prend en charge l’exécution par lots d’instructions avec des paramètres d’entrée, cela signifie l’envoi de plus d’un ensemble de paramètres lors de l’exécution de l’instruction. L’interface de traitement par lots est conçue (principalement) pour répondre aux exigences de JDBC en matière de traitement par lots des instructions préparées, mais elle présente un certain nombre de différences majeures :

L’interface IBatch (tout comme IResultSet) peut être créée de deux manières, en utilisant l’interface IStatement ou IAttachment, qui appellent toutes deux la méthode createBatch() de l’interface correspondante.Dans le second cas, le texte de l’instruction SQL à exécuter dans le lot est passé directement à createBatch(). Le traitement par lots est configuré à l’aide du bloc Paramètres Batch, dont le format est plus ou moins similaire à celui de DPB v.2 – au début, il y a une balise (IBatch::CURRENT_VERSION), suivie d’un ensemble de clusters larges : une balise de 1 octet, une longueur de 4 octets, la valeur de la longueur d’octet spécifiée. Les balises possibles sont décrites dans l’interface de traitement par lots.Le moyen le plus simple (et recommandé) de créer un bloc de paramètres pour la création par lots est d’utiliser l’interface appropriée IXpbBuilder :

L’utilisation d’un tel bloc de paramètres indique au paquet de renvoyer le nombre d’enregistrements mis à jour pour chaque message.

Pour créer une interface batch avec les paramètres requis, passez le bloc de paramètres à l’appel createBatch() :

Dans cet exemple, l’interface de traitement par lots est créée avec le format de message par défaut, car « NULL » est transmis à la place du format de métadonnées d’entrée.

Pour travailler avec l’interface de traitement par lots créée, nous devons connaître le format des messages qu’elle contient.Il peut être récupéré à l’aide de la méthode getMetadata() :

Bien sûr, si vous avez passé votre propre format de message à un lot, vous pouvez simplement l’utiliser.

De plus, je suppose qu’il existe une fonction fillNextMessage(unsigned char* data, IMessageMetadata* metadata) et qu’elle peut remplir le tampon data selon le format passé metadata. Pour travailler avec les messages, nous avons besoin d’un tampon pour les données :

Maintenant, nous pouvons ajouter plusieurs messages avec des données remplies au lot :

Une autre façon de travailler avec les messages (à l’aide de la macro FB_MESSAGE) est présente dans l’exemple de l’interface de traitement par lots 11.batch.cpp.

Enfin, le lot devrait être exécuté :

Nous avons demandé un décompte du nombre d’enregistrements modifiés (insérés, mis à jour ou supprimés) pour chaque publication. Pour l’afficher, nous devons utiliser l’interface IBatchCompletionState.Déterminez le nombre total de messages traités par le lot (il peut être inférieur au nombre de messages envoyés au lot si une erreur s’est produite et que l’option permettant de renvoyer plusieurs erreurs pendant le traitement par lots n’a pas été activée) :

Affichons maintenant l’état de chaque message :

Lorsque vous avez terminé d’analyser l’état d’achèvement, n’oubliez pas de le supprimer :

Un exemple complet d’affichage du contenu IBatchCompletionState peut être trouvé dans la fonction print_cs() dans l’exemple 11.batch.cpp.

Si, pour une raison quelconque, vous souhaitez vider les tampons de traitement sans les exécuter (c’est-à-dire pour préparer le traitement d’un nouveau lot de messages), utilisez la méthode cancel() :

Comme le reste de nos interfaces d’accès aux données, IBatch dispose d’une méthode spéciale pour la fermer :

Au lieu de cela, vous pouvez utiliser l’appel standard release() si vous ne vous souciez pas des erreurs :

Ces techniques vous aident à mettre en œuvre tout ce dont vous avez besoin pour les opérations par lots de type JDBC avec des instructions préparées.

Vous pouvez ajouter plus d’un message par appel à un lot. Cela étant dit, n’oubliez pas que les messages doivent être correctement alignés pour que cette fonctionnalité fonctionne correctement. L’alignement requis et la taille du message aligné doivent être obtenus à partir de l’interface IMessageMetadata, par exemple :

Plus tard, cette taille sera utile lors de la sélection et de l’utilisation d’un tableau de messages :

Après cela, le lot peut être exécuté ou le lot suivant de messages peut y être ajouté.

Les objets blob sont généralement incompatibles avec les lots : batch est efficace lorsque vous devez transférer beaucoup de petites données vers le serveur en une seule étape, les champs blob sont traités comme des objets volumineux, et il n’est donc pas logique de les utiliser dans des lots en général.Mais dans la pratique, il arrive souvent que les BLOB ne soient pas trop volumineux – auquel cas l’utilisation de l’API BLOB traditionnelle (création d’un blob, envoi de segments vers le serveur, fermeture du blob, passage de l’ID BLOB dans un message) tue les performances, en particulier lorsqu’il est utilisé sur le WAN. Par conséquent, dans Firebird, le paquet prend en charge l’envoi de BLOB au serveur avec d’autres messages.Pour utiliser cette fonctionnalité, vous devez d’abord définir la stratégie d’utilisation d’objets blob pour le package que vous créez (en tant qu’option dans le bloc Paramètres) :

Dans cet exemple, les objets BLOB temporaires nécessaires pour maintenir la communication entre le BLOB et le message dans lequel ils sont utilisés seront générés par le moteur Firebird : il s’agit de l’utilisation la plus simple et la plus courante.Imaginez que le message soit décrit comme suit :

Dans ce cas, pour envoyer un message contenant un objet blob au serveur, vous pouvez faire quelque chose comme ceci :

Si un objet blob est trop grand pour tenir dans votre mémoire tampon existante, vous pouvez utiliser la méthode appendBlobData() au lieu de redimentionner la mémoire tampon.Il ajoute plus de données au dernier BLOB ajouté.

Après avoir ajouté la première partie du BLOB, récupérez la donnée suivante dans descriptionText, avec la taille descriptionSize puis :

Cela peut être fait en boucle, mais veillez à ne pas trop remplir les tampons de lots internes : leur taille est contrôlée par le paramètre BUFFER_BYTES_SIZE lors de la création de l’interface IBatch, mais ne peut pas dépasser 256 Mo (16 Mo par défaut). Si vous avez besoin de traiter un blob aussi volumineux (par exemple, dans le contexte de nombreux petits blobs, ce qui peut expliquer l’utilisation du traitement par lots), utilisez simplement l’API standard IBlob et la méthode registerBlob de l’interface IBatch.

Un autre choix possible pour une stratégie BLOB est BLOB_IDS_USER. À première vue, l’utilisation ne change pas grand-chose — avant d’appeler addBlob(), l’identifiant correct et unique de chaque blob doit être placé dans la mémoire référencée par le dernier paramètre. Bien entendu, le même identifiant doit être transmis dans le message pour le BLOB.Étant donné que la génération d’objets blob par le moteur est très rapide, une telle politique peut sembler inutile, mais imaginez un cas où vous obtenez des objets blob et d’autres données dans des threads indépendants (par exemple, des blocs de fichiers) et où de bons ID sont déjà présents. Dans ce cas, l’utilisation de BLOB fournis par l’utilisateur peut grandement simplifier le code.

Bien entendu, le BPB téléchargé peut contenir d’autres paramètres de création de BLOB. Comme vous l’avez peut-être déjà remarqué, vous pouvez également passer BPB directement à addBlob(), mais si la plupart des blobs que vous allez ajouter sont dans le même format différent du format par défaut, alors l’utilisation de setDefaultBpb() est un peu plus efficace.Pour en revenir aux blobs partitionnés, l’appel de addBlob() ajoutera la première partition à l’objet blob, les appels suivants à appendBlobData() ajouteront d’autres partitions. N’oubliez pas que la taille du segment est limitée à « 64 Ko – 1 », essayer de transférer plus de données en un seul appel provoquera une erreur.

L’étape suivante consiste à travailler avec des flux BLOB existants, qui utilisent la méthode addBlobStream().En l’utilisant, vous pouvez ajouter plus d’un BLOB à un lot en un seul appel. Un flux BLOB est une séquence de BLOB, chacun d’entre eux commençant par un en-tête BLOB. L’en-tête doit être correctement aligné — pour cela, il y a un appel spécial dans l’interface IBatch :

Il est supposé que tous les composants du flux BLOB dans le lot doivent être alignés au moins sur la limite d’alignement, y compris la taille des portions de flux passées à addBlobStream(), qui doit être un multiple de cet alignement.L’en-tête contient 3 champs : un objet BLOB de 8 octets (qui doit être différent de zéro), une taille totale de BLOB de 4 octets et une taille BPB de 4 octets.La taille totale d’un objet blob inclut le BPB à l’intérieur, ce qui signifie que vous pouvez toujours trouver l’objet blob suivant dans le flux dans un octet de taille d’objet blob après l’en-tête (y compris l’alignement). Le BPB (s’il est présent, c’est-à-dire si la taille du BPB n’est pas nul) est placé immédiatement après l’en-tête. Une fois que les données de l’objet blob BPB sont transférées, le format de l’objet blob varie selon que l’objet blob est diffusé en continu ou partitionné. Dans le cas d’un blob en streaming, il s’agit d’une simple séquence d’octets dont la taille est blob-size – BPB-size.Avec un blob partitionné, les choses sont un peu plus compliquées : les données de l’objet blob sont une collection de partitions, où chaque partition a le format suivant : la taille du segment est de 2 octets (elle doit être alignée sur la limite de IBatch::BLOB_SEGHDR_ALIGN), suivie des 2 octets du nombre d’octets qui y sont stockés.

Lorsqu’un BLOB est ajouté à un flux, sa taille n’est pas toujours connue à l’avance. Pour éviter d’avoir une mémoire tampon trop grande pour cet objet blob (n’oubliez pas que la taille doit être spécifiée dans l’en-tête BLOB avant les données de l’objet blob), vous pouvez utiliser un enregistrement de continuation BLOB. Dans l’en-tête BLOB, vous laissez la taille du BLOB avec la valeur connue lors de la création de l’en-tête, et ajoutez un enregistrement de continuation qui a exactement le même format que l’en-tête BLOB, mais ici l’ID BLOB doit être égal à zéro, et la taille du BPB doit toujours être également nulle. En règle générale, vous aurez besoin d’une entrée de continuation pour chaque appel à addBlobStream().

Cette dernière méthode, qui est utilisée pour travailler avec les BLOB, est distincte des trois premières, qui transmettent les données BLOB avec le reste des données du lot - elle doit s’enregistrer dans l’identifiant du package BLOB créé à l’aide de l’API BLOB standard.Cela peut être inévitable si vous souhaitez empaqueter un blob très volumineux. N’utilisez pas l’ID d’objet blob dans le lot, car cela entraînerait une erreur d’ID d’objet blob non valide lors de l’exécution du lot. Au lieu de cela, exécutez :

Si la politique BLOB amène le moteur Firebird à générer des BLOB, ce code est suffisant pour enregistrer correctement le BLOB existant dans le lot. Dans d`autres cas, vous devrez assigner l`identificateur correct (à partir du paquet POV) pour msg→desc.

Presque toutes les méthodes mentionnées sont utilisées dans 11.batch.cpp - utilisez-le pour voir un exemple en direct de traitement par lots dans firebird.

Quelques mots sur l’accès aux traitements par lots à partir de l’API ISC - vous pouvez exécuter une instruction ISC préparée en mode batch.Pour ce faire, deux nouvelles fonctions d’API ont été ajoutées, à savoir fb_get_transaction_interface et fb_get_statement_interface, qui permettent d’accéder à des interfaces pertinentes identiques aux descripteurs ISC existants. Un exemple de ceci est présent dans le 12.batch_isc.cpp.

L’interface utilisateur de l’événement n’a pas été finalisé dans Firebird 4.0, nous nous attendons à ce qu’il y ait quelque chose de plus intéressant dans la prochaine version. Le support minimum existant est le suivant : IAttachment contient la méthode queEvents(), qui remplit presque les mêmes fonctions que l’appel isc_que_events().Au lieu de la paire de paramètres FPTR_EVENT_CALLBACK ast et void* arg nécessaires pour appeler le code utilisateur lorsqu’un événement se produit dans Firebird, l’interface de rappel IEventCallback est utilisée. Il s’agit d’une approche traditionnelle qui permet d’éviter les appels vide* dangereux dans une fonction personnalisée. Une autre différence importante est qu’au lieu d’un identificateur d’événement (une sorte de gestionnaire), cette fonction renvoie une référence à l’interface IEvents, qui a une méthode cancel() utilisée pour arrêter l’événement d’écoute. Contrairement à l’identifiant, qui est détruit automatiquement à l’arrivée d’un événement, une interface ne peut pas être détruite automatiquement si l’événement est reçu juste avant l’appel de la méthode cancel(), cela provoquera une erreur de segmentation car l’interface sera déjà détruite. Par conséquent, une fois l’événement reçu, l’interface IEvents doit être explicitement libérée. Cela peut être fait, par exemple, juste avant de demander un événement à la file d’attente:

Définir le pointeur de l’interface à NULL est utile en cas d’exception dans queEvents. À d’autres égards, la gestion des événements n’a pas changé par rapport à l’API ISC. Pour plus d’informations, utilisez notre exemple 08.events.cpp.

Les plugins interagissent activement avec un composant spécial de Firebird appelé le gestionnaire de plugins. En particulier, le gestionnaire de plugins doit savoir quels modules de plugins ont été chargés et doit être averti si le système d’exploitation tente de décharger l’un de ces modules sans une commande explicite du gestionnaire de plugins (cela peut se produire principalement lors de l’utilisation du serveur embarqué — lorsque le programme appelle exit() ou que la bibliothèque principale de Firebird fbclient est déchargée). L’objectif principal de l’interface IPluginModule est la notification. Tout d’abord, vous devez décider comment informer Firebird que le module sera déchargé. Lorsqu’une bibliothèque dynamique est déchargée pour une raison quelconque, de nombreuses actions spécifiques au système d’exploitation sont effectuées, et certaines de ces actions peuvent être utilisées pour détecter ce fait dans le programme. Lors de l’écriture de plugins distribués avec firebird, nous utilisons toujours l’appel global de destructeur de variables. Le gros « plus » de cette méthode est qu’elle est indépendante du système d’exploitation (bien que la fonction exit() puisse également être utilisée avec succès). Mais l’utilisation d’un destructeur permet de concentrer facilement presque tout ce qui concerne la détection de déchargement dans une seule classe, tout en implémentant l’interface IPluginModule.

La mise en œuvre minimale est la suivante :

Le seul membre des données est l’interface du gestionnaire de plugins IPluginManager. Il est passé à la fonction registerModule() et stocké dans une variable privée, tandis que le module est enregistré dans le gestionnaire de plugins en utilisant la méthode callModule() avec sa propre adresse comme seul paramètre. La variable pluginManager stocke non seulement un pointeur vers l’interface, mais sert également d’indicateur indiquant que le module est enregistré. Lorsque le destructeur d’un module enregistré est appelé, il avertit le gestionnaire de plugin d’un déchargement inattendu avec un appel à unregisterModule() qui passe le pointeur à lui-même. Lorsque le gestionnaire de plugins décharge le module sur une base régulière, la première chose que l’appel de la méthode doClean() est de changer l’état du module en unregistered, ce qui évite l’appel à unregisterModule().

Après avoir implémenté l’interface du plugin IPluginModule, nous sommes tombés sur la première interface nécessaire pour implémenter les plugins – IPluginManager. Il sera activement utilisé plus tard, il est peu probable que vous ayez besoin du reste des membres de cette classe après l’avoir copié dans votre programme. N’oubliez pas de déclarer une variable globale de ce type et d’appeler la fonction registerMe() à partir de FB_PLUGIN_ENTRY_POINT.

Commençons à implémenter le plugin lui-même. Le type de l’interface principale dépend évidemment du type de plugin, mais ils sont tous basés sur l’interface générale IPluginBase avec comptage de références, qui effectue des tâches communes (et très simples) pour tous les plugins. Chaque plugin a un objet (également avec comptage de liens) auquel il appartient. Afin d’effectuer une gestion intelligente du cycle de vie des plugins, tout plugin doit être en mesure de stocker des informations sur le propriétaire et de les transmettre au gestionnaire de plugins sur demande. Cela signifie que chaque plugin doit implémenter les deux méthodes triviales setOwner() et getOwner() contenues dans l’interface IPluginBase. Les méthodes dépendantes du type de plugin sont certainement plus intéressantes — elles sont discutées dans la partie description de l’interface.

Jetons un coup d’œil à la partie implémentation typique de n’importe quel plugin (j’utilise spécifiquement le type SomePlugin inexistant ici) :

Le constructeur reçoit l’interface de configuration du plugin en tant que paramètre. Si vous comptez configurer le plugin d’une manière ou d’une autre, il est recommandé d’enregistrer cette interface dans votre plugin et de l’utiliser plus tard. Cela vous permettra d’utiliser le style de configuration global de Firebird, ce qui permettra aux utilisateurs d’avoir une configuration familière et de minimiser le codage. Bien sûr, lors de l’enregistrement d’une interface de lien, il est préférable de ne pas oublier d’y ajouter un lien. N’oubliez pas non plus de définir le nombre de liens sur 0 et le propriétaire du plugin sur NULL.

Le destructeur libère l’interface de configuration. Notez que nous ne modifions pas le nombre de liens de notre propriété car elle ne nous appartient pas.

Il s’agit d’une implémentation tout à fait typique d’un objet avec comptage de références.

Comme promis, l’implémentation d’IPluginBase est triviale.

Dans cet exemple, la partie formelle de l’implémentation de l’interface principale du plugin est terminée. Après avoir ajouté des méthodes spécifiques au type (et peut-être écrit du code pour les rendre utiles), l’interface est prête.

Une autre interface requise pour que le plugin fonctionne est IPluginFactory. La class instancie le plugin et le renvoie au gestionnaire de plugins. La class ressemble généralement à ceci :

Il faut faire attention au fait que même dans le cas où le code de la fonction peut lever des exceptions (le nouvel opérateur peut lever une exception lorsque la mémoire est épuisée), vous n’avez pas toujours besoin de définir manuellement le bloc try/catch - l’implémentation des interfaces Firebird fait le travail pour vous, dans l’implémentation IPluginFactory ce traitement a lieu dans le modèle IPluginFactoryImpl. Notez que les shims d’état par défaut ne gèrent que l’exception FbException. Mais si vous travaillez sur un grand projet, définissez votre propre wrapper, auquel cas vous pouvez gérer n’importe quel type d’exception C++ et transmettre des informations utiles à ce sujet à partir de votre plugin.

Lorsque le gestionnaire de plugins charge un module de plugin, il appelle la routine d’initialisation du module, qui est la seule fonction FB_PLUGIN_ENTRY_POINT du plugin exportée. Pour écrire le code, il aura besoin de deux variables globales : le module de plugin et la constructeur de plugins. Dans notre cas, il s’agit de :

Si un module contient plus d’un plugin, vous aurez besoin d’un constructeur pour chaque plugin.

Pour FB_PLUGIN_ENTRY_POINT il ne faut pas oublier qu’il doit être exporté depuis le module plugin, cela nécessite de prendre en compte certaines caractéristiques du système d’exploitation. Pour ce faire, nous utilisons la macro FB_DLL_EXPORT définie dans examples/interfaces/ifaceExamples.h. Si vous êtes sûr que vous n’utilisez le plugin que pour un système d’exploitation spécifique, vous pouvez rendre cet endroit un peu plus facile. Au minimum, la fonction doit enregistrer le module et toutes les constructeurs dans le gestionnaire de plugins :

Tout d’abord, nous appelons la fonction récemment écrite PluginModule::registerMe(), qui enregistre le IPluginManager pour une utilisation ultérieure et enregistre notre module de plugin. Enregistrez ensuite la class (ou les class s’il y aura plusieurs plugins dans un module). Nous devons passer le bon type de plugin (les types valides sont listés dans l’interface IPluginManager) et le nom sous lequel le plugin sera enregistré. Dans le cas le plus simple, il devrait être le même que le nom de la bibliothèque dynamique du plugin. Cette règle vous aidera à ne pas configurer le plugin manuellement dans plugins.conf.

Notez que contrairement aux applications, les plugins n’ont pas besoin d’utiliser fb_get_master_interface() pour obtenir iMaster. Au lieu de cela, vous devez utiliser l’instance passée à FB_PLUGIN_ENTRY_POINT. Si vous avez besoin d’une interface iMaster dans votre plugin, assurez-vous de la conserver dans cette fonctionnalité.

L’interface IAttachment remplace isc_db_handle.

Interface IDtc — Coordonnatrice des transactions distribuées Permet de démarrer une transaction distribuée (fonctionne avec deux connexions ou plus). Contrairement à l’approche pré-FB3, où une transaction distribuée doit être démarrée de cette manière dès le début, le Firebird 3 Distributed Transaction Coordinator vous permet également de joindre des transactions déjà en cours en une seule transaction distribuée.

Interface IDtcStart — remplace le tableau des structures TEB (passé isc_start_multiple() à l’API ISC). Cette interface rassemble les connexions (et les TPB correspondants) pour lesquelles la transaction distribuée doit être démarrée.

Interface IEventCallback — Remplace la fonction d’événement utilisée dans l’appel isc_que_events(). Doit être implémenté par l’utilisateur pour suivre les événements à l’aide de la méthode IAttachment::queEvents().

Interface IEvents — Remplace l’ID d’événement lors de l’utilisation de la surveillance des événements.

Interface IFirebirdConf — l’accès à la configuration de base de Firebird.Il est utilisé à la fois pour la configuration par défaut spécifiée par la configuration firebird.conf et pour chaque base de données connectée avec database.conf. Pour accélérer l’accès aux valeurs de configuration, les appels qui accèdent aux valeurs réelles utilisent une clé entière au lieu d’un nom de paramètre symbolique. La clé est stable pendant que le serveur est en cours d’exécution (c’est-à-dire que le plugin peut la récupérer une fois et l’utiliser pour obtenir la valeur des paramètres de configuration pour différentes bases de données).

L’interface IInt128 permet de travailler avec des entiers de 128 bits, qui est utilisé comme type de base pour les nombres numériques et décimaux avec une précision de plus de 18.

IMaster — L’interface principale à partir de laquelle toutes les opérations avec l’API Firebird commencent.

Interface MessageMetadata — analogue partiel de XSQLDA (ne contient pas de données de message, mais uniquement des informations sur le format du message).Utilisé dans les appels liés à l’exécution d’instructions SQL.

Un exemple de mise en cache des messages avec IMessageMetadata en Pascal:

Interface IMetadataBuilder — Permet de décrire les types de données des messages existants ou de créer des métadonnées.

Interface IOffsetsCallback

L’interface IBatch vous permet de traiter plusieurs ensembles de paramètres dans une seule instruction.

Balise pour le bloc de paramètres :

Balises pour les clusters dans le bloc de paramètres :

Stratégies utilisées pour stocker les objets BLOB :

Éléments autorisés dans l’appel getInfo() :

Interface IPluginConfig — est transmis au constructeur de plugins lorsque vous créez une instance du plugin (avec une configuration spécifique).

Interface IPluginFactory — doit être implémenté par l’auteur du plugin lors de l’écriture du plugin.

Interface IPluginManager — API du gestionnaire de plugins.

Constantes définies par l’interface IPluginManager (types de plugins) :

Interface IPluginModule — représente un module de plugin (bibliothèque dynamique). Doit être implémenté par l’auteur du plugin dans chaque module du plugin (une instance par module).

Interface IPluginSet — est un ensemble de plugins de ce type.Couramment utilisé par le code interne de Firebird, mais recommandé pour une utilisation dans les plugins qui chargent d’autres plugins.

Interface IPluginModule — L’interface principale pour démarrer l’accès à la base de données/service.

Interface IResultSet — remplace (avec des fonctionnalités étendues) certaines des fonctions isc_stmt_handle. Cette interface est retournée en appelant openCursor() à partir de IAttachment ou IStatement. Tous les appels à fetch…​ à l’exception de fetchNext() ne fonctionnent que pour le curseur bidirectionnel (ouvert avec l’option CURSOR_TYPE_SCROLLABLE).

Interface IService — Remplace isc_svc_handle.

Interface IStatement — remplace (partiellement) isc_stmt_handle.

Constantes définies par l’interface IStatement

Flag IAttachment::prepare():

Les flags suivants peuvent être combinés avec OU pour produire l’effet souhaité :

Pour les combinaisons d’indicateurs les plus couramment utilisées, vous pouvez utiliser les constantes suivantes :

Les valeurs renvoyées par l’attribut getFlags():

Les flags passés à openCursor():

L’interface IStatus remplace ISC_STATUS_ARRAY. La fonctionnalité a été étendue : l’état a un accès séparé aux vecteurs d’erreur et d’avertissement, peut contenir des vecteurs de longueur illimitée, stocke indépendamment les chaînes utilisées dans les vecteurs et n’a pas besoin d’un tampon de chaînes de caractères. Dans C++, IStatus est toujours utilisé dans le wrapper d’état, l’API C++ fournit deux wrappers différents qui ont un comportement différent lorsqu’une erreur est renvoyée par un appel d’API. L’interface a été réduite au minimum (des méthodes telles que la conversion en ext ont été déplacées vers l’interface IUtil pour la rendre plus facile à implémenter par les utilisateurs en cas de besoin.

Les constantes définies dans IStatus

Les flags renvoyés par l’attribut getState():

Codes d’achèvement :

IBatchCompletionState — Une interface à usage unique, toujours retournée par la méthode execute() de l’interface IBatch.Il contient plus ou moins (en fonction des paramètres passés lors de la création de l’IBatch) des informations détaillées sur les résultats de l’exécution du lot.

Valeurs spéciales renvoyées par getState() :

La valeur spéciale renvoyée par findError() est :

Interface ITimer — Minuterie personnalisée. Une interface de rappel qui doit être implémentée par l’utilisateur pour utiliser le minuteur Firebird.

L’interface ITimerControl est une implémentation très simple et peu précise du timer. Nous en sommes arrivés là parce que les minuteries existantes sont très dépendantes du système d’exploitation et peuvent être utilisées dans des programmes qui nécessitent une portabilité et ne nécessitent pas une minuterie de très haute précision. De plus, l’exécution d’une minuterie donnée peut être reportée si l’autre minuterie n’a pas été terminée au moment où cette minuterie devrait être signalée.

Interface ITransaction — Remplace isc_tr_handle.

Interface IVersionCallback — Rappel pour IUtil::getFbVersion().

Interface IUtil — Diverses méthodes d’aide.

Interface IXpbBuilder

Constantes définies par l’interface IXpbBuilder

Types de constructeurs valides :

Les algorithmes permettant de crypter des données à différentes fins sont bien connus depuis de nombreuses années. Le seul "petit" problème typique qui subsiste est de savoir où obtenir la clé top secrète utilisée par cet algorithme. Heureusement, pour le cryptage du trafic réseau, il existe une bonne solution : une clé de cryptage unique doit être générée par le plugin d’authentification. Au moins, le plugin SRP par défaut peut produire une telle clé. Et cette clé est résistante aux attaques, y compris celles de type "man-in-the-middle". C’est pourquoi une méthode a été choisie pour fournir des clés au plugin wire crypt : les obtenir du plugin d’authentification. (Dans le cas où le plugin d’authentification utilisé ne peut pas fournir de clé, un pseudo-plugin peut être ajouté dans les listes AuthClient et AuthServer pour produire des clés, quelque chose comme deux paires privées/publiques asymétriques).

L’interface ICryptKey est utilisée pour stocker la clé fournie par le plugin d’authentification et la transmettre au plugin de chiffrement du trafic réseau. Cette interface doit être utilisée de la manière suivante : lorsque le plugin d’authentification du serveur ou du client est prêt à fournir une clé, il demande IServerBlock ou IClientBlock pour créer une nouvelle interface ICryptKey et y stocke la clé. Un type de clé adapté à IWireCryptPlugin sera sélectionné par Firebird et passé à cette interface.

L’interface IWireCryptPlugin est l’interface principale du plugin de chiffrement réseau. Comme toute autre interface de ce type, elle doit être implémentée par l’auteur du plugin.

Le plugin d’authentification contient deux parties obligatoires, une partie client et une partie serveur, et peut également contenir une troisième partie qui lui est associée, le gestionnaire d’utilisateurs. Pendant le processus d’authentification, le client Firebird appelle le plugin client et envoie les données générées par celui-ci au serveur, puis le serveur appelle le plugin serveur et envoie les données qu’il a générées au client. Ce processus est répété jusqu’à ce que les deux plugins renvoient le code AUTH_MORE_DATA.AUTH_SUCCESS renvoyé côté serveur signifie une authentification réussie, AUTH_FAILED de part et d’autre signifie une interruption immédiate du processus itératif et un rejet signalé au client, AUTH_CONTINUE signifie que le plugin suivant de la liste des plugins d’authentification configurés doit être coché.

Il n`y a pas d`exemples dédiés de plugins d`authentification, mais dans le code source de firebird, dans le répertoire src/auth, vous pouvez trouver le plugin AuthDbg, avec lequel vous pouvez apprendre à partir d`un exemple trivial (sans calculs complexes comme dans Srp, par exemple, et sans appeler des fonctions WinAPI folles comme dans AuthSspi), comment le côté client et le côté serveur effectuent l`authentification (handshake).

L’interface IAuth ne contient pas de méthodes, seules quelques constantes de définition de code sont renvoyées par la méthode authenticate() à IClient et IServer.

Interface IWriter — Enregistre le bloc Paramètre d’authentification.

L’interface IBlob remplace l’interface isc_blob_handle.

L’interface IServerBlock est utilisée par le serveur du module d’authentification pour communiquer avec le client.

L`interface IServer est l`interface principale du plugin d`authentification.

L’interface IClientBlock est utilisée par le côté client du module d’authentification pour communiquer avec le serveur.

L’interface IClient est l’interface principale côté client du module d’authentification.

Ce plugin est activement lié au backend d’authentification – il prépare une liste d’utilisateurs pour le plugin d’authentification. Chaque plugin d’authentification nécessite un gestionnaire d’utilisateurs – certains d’entre eux peuvent accéder à une liste d’utilisateurs créés à l’aide d’un logiciel autre que Firebird (par exemple, AuthSspi). Un enregistrement de description utilisateur se compose de plusieurs champs et peut prendre en charge plusieurs opérations telles que l’ajout d’un utilisateur, la modification d’un utilisateur, la récupération d’une liste d’utilisateurs, etc. Le plugin doit être capable d’interpréter les commandes reçues dans l’interface IUser.

L’interface IUserField n’est pas utilisée comme une interface autonome, c’est l’interface de base pour ICharUserField et IIntUserField.

NULL, S’ils sont utilisés, ils sont désignés par les implémentations comme des interfaces et ont donc un accès complet à leurs composants internes.

Interface ICharUserField:

Interface IIntUserField:

L’interface IUser est une liste de méthodes permettant d’accéder aux champs inclus dans un enregistrement utilisateur.

Les constantes définies par l’interface utilisateur sont les opcodes effectifs.

Interface IListUsers — Il s’agit du callback utilisé par le plugin d’authentification lors de la demande d’une liste d’utilisateurs. Le plugin remplit l’interface IUser pour tous les éléments de la liste d’utilisateurs un par un, et appelle la méthode list() de l’interface pour chaque utilisateur.

L’interface ILogonInfo contient les données transmises au plugin de gestion des utilisateurs pour se connecter à la base de données de sécurité avec des informations d’identification valides.

Interface IConfig — L’interface générale du fichier de configuration.

L’interface IManagement est l’interface principale du plugin de gestion des utilisateurs.

La possibilité de chiffrer la base de données est présente dans Firebird depuis l’époque d’Interbase, mais les endroits correspondants dans le code ont été commentés. La mise en œuvre était discutable : la clé de chiffrement était toujours envoyée du client au DPB, aucune tentative n’était faite pour la cacher au monde extérieur et aucun chemin n’était proposé pour chiffrer les bases de données existantes. Firebird 3.0 résout la plupart des problèmes, à l’exception probablement du pire : comment gérer les clés de chiffrement. Nous proposons différents types de solutions, mais elles demandent des efforts dans les plugins, c’est-à-dire qu’il n’y a pas de façon agréable de travailler avec des clés comme, par exemple, pour les plugins pour crypter le trafic réseau.

Avant d’exécuter votre propre plugin de chiffrement de base de données, vous devez tenir compte des éléments suivants : Il existe deux cas principaux dans lesquels le chiffrement de base de données est utilisé : premièrement, il peut être nécessaire d’éviter les fuites de données si le serveur de base de données est physiquement volé, et deuxièmement, il peut être utilisé pour protéger les données d’une base de données distribuée avec une application spéciale accédant à ces données. Les exigences pour ces cas sont complètement différentes. Dans le premier cas, nous pouvons faire confiance au serveur de base de données qu’il n’est pas modifié pour voler les clés transmises au plugin de sécurité, c’est-à-dire que nous nous attendons à ce que cette clé ne soit pas envoyée au mauvais serveur. Dans le second cas, le serveur peut être modifié d’une manière ou d’une autre pour voler des clés (si elles sont transmises de l’application au plugin via le code du serveur) ou même des données (en tant que dernier endroit pour vider le cache, où elles ne sont pas chiffrées). Par conséquent, votre plugin doit s’assurer qu’il fonctionne avec les binaires Firebird non modifiés et votre application avant d’envoyer la clé au plugin, par exemple, le plugin peut nécessiter une sorte de signature numérique de leur part. De plus, si vous utilisez l’accès réseau au serveur, il est conseillé de vérifier que le canal réseau est chiffré (en analysant la sortie de IUtil::getFbVersion()) ou en utilisant votre propre clé de chiffrement.Tout ce travail doit être effectué dans le plugin (et dans l`application qui fonctionne avec), ce qui signifie que l`algorithme de chiffrement des blocs de base de données lui-même peut être la partie la plus simple du plugin de chiffrement de base de données, en particulier lorsqu`il utilise une bibliothèque standard.

L’interface ICryptKeyCallback doit permettre à la clé de chiffrement d’être transmise au plugin de chiffrement de base de données ou au plugin du détenteur de la clé.

Les valeurs suivantes peuvent être renvoyées par cette fonction :

L’interface IDbCryptInfo est passée au moteur IDbCryptPlugin. Le plugin peut enregistrer cette interface et l’utiliser en cas de besoin pour obtenir plus d’informations sur la base de données.

L’interface IDbCryptPlugin est l’interface principale du plugin de chiffrement de base de données.

Ce type de plugin est nécessaire pour différencier la fonctionnalité – le plugin de cryptage de base de données s’occupe du cryptage proprement dit, le détenteur de la clé résout les problèmes liés à la fourniture de la clé de manière sécurisée. Le plugin peut récupérer la clé à partir de l’application ou la télécharger d’une autre manière (jusqu’à utiliser une clé USB insérée dans le serveur au démarrage de Firebird).

L’interface IKeyHolderPlugin est l’interface principale pour le plugin de stockage de clé de chiffrement.

Interface IConfigManager — Une interface commune pour accéder à divers objets de configuration.

Catalogue des codes :

Interface IConfigEntry — représente une entrée (Clé = Valeurs avec sous-titres possibles (sous-entrées)) dans le fichier de configuration de firebird.

L’interface IDecFloat16 permet de travailler avec le type de données DECFLOAT(16).

L’interface IDecFloat34 permet de travailler avec le type de données DECFLOAT(34).

Les 3 classes suivantes sont utilisées pour représenter les types DATE, TIME et TIMESTAMP (datetime) lors de l’utilisation de la macro FB_MESSAGE. Les membres de la structure de données qui représentent un message statique correspondent aux champs des types FB_DATE/FB_TIME/FB_TIMESTAMP et auront le type de l’une de ces classes. Pour accéder aux champs de date et d’heure dans les messages statiques, vous devez connaître les méthodes et les membres de la classe (qui sont suffisamment auto-descriptifs pour ne pas être décrits ici).

Méthodes de classe FbDate:

Méthodes de classe FbTime:

Membres du groupe `FbTimestamp `:

Les deux modèles suivants sont utilisés dans les messages statiques pour représenter les champs CHAR(N) et VARCHAR(N).