Commencer à utiliser l'API .NET ForexConnect (Win32/Win64)

Cet article explique comment commencer à utiliser l'API .NET ForexConnect. Vous trouverez ici des explications sur les principes de bases de l'API et des instructions étapes par étapes pour la création d'un modèle de travail ou d'une application de trading simple.

Plateforme : Microsoft .NET Framework 2.0 et, ensuite, MS Windows versions 32 bits/64 bits.
Langage : C# .NET
IDE : Microsoft Visual Studio 2005, 2008, 2010

L'utilisation de bibliothèques ForexConnect .NET avec l'infrastructure d'application Microsoft Silverlight n'est pas prise en charge.
L'exécution de bibliothèques ForexConnect .NET avec Mono n'est pas prise en charge.

Obtenir et installer les bibliothèques de l'API ForexConnect

1. Téléchargez la dernière version de l'API ForexConnect :
   • Si vous disposez de la version 32 bits de Microsoft Windows, téléchargez la version 32 bits de l'API ForexConnect.
   • Si vous disposez de la version 64 bits de Microsoft Windows, téléchargez la version 64 bits de l'API ForexConnect.

   Consultez la boîte de dialogue Propriétés système pour connaître votre version de Windows.

   Si vous êtes équipé de Windows XP et que la mention « édition x64 » n'apparaît pas dans la boîte de dialogue Propriétés système, cela signifie que vous disposez d'une version 32 bits de Windows XP.

2. Démarrez le programme d'installation et suivez les instructions de l'Assistant Installation.

Dans la suite de cet article, nous supposerons que l'API ForexConnect a été installée dans le dossier C:\Program Files\Candleworks\ForexConnectAPI\.

Utiliser l'API ForexConnect avec Microsfot Visual Studio

Vous devez appliquer les modifications suivantes à votre projet C# :

1. Configurez l'événement post-build de votre projet afin de copier les bibliothèques et les fichiers de prise en charge de l'API ForexConnect vers le dossier de création de votre programme :

Dans Propriétés du projet → Événements de génération → Ligne de commande de l'événement après génération, ajoutez le texte suivant :

copy "C:\Program Files\Candleworks\ForexConnectAPI\bin\*.*" "$(TargetDir)"

2. Ajoutez une référence à l'assembly .NET fxcore2.dll dans votre projet.

• Si vous utilisez .NET 4.0, utilisez l'assembly .NET fxcore2.dll approprié qui se trouve dans le dossier "C:\Program Files\Candleworks\ForexConnectAPI\bin\net\dotnet40\".
• Si vous utilisez .NET 2.0, utilisez l'assembly fxcore2.dll qui se trouve dans le dossier "C:\Program Files\Candleworks\ForexConnectAPI\bin\net\dotnet20\".

3. Ajoutez l'espace de noms fxcore2 à votre code :

        using fxcore2;

Distribution

Vous devez distribuer votre programme avec toutes les bibliothèques binaires et les fichiers de prise en charge de "C:\Program Files\Candleworks\ForexConnectAPI\bin". Les bibliothèques ForexConnect et les fichiers de prise en charge doivent se trouver dans le dossier où est installée votre application.

Notez que l'assembly fxcore2.dll doit également se trouver dans le dossier où votre application est installée.

Caractéristiques de l'API .NET ForexConnect

Architecture orientée événement

Toutes les API utilisées par ForexConnect sont asynchrones. Vous devrez donc intégrer une architecture orientée événement à votre code.

Une architecture orientée événement est un modèle d'architecture logicielle qui gère le comportement de la production, de la détection et de la consommation d'événements ainsi que les réponses qu'ils invoquent. Dans ce contexte, un événement doit être traité comme une valeur ou un message pouvant être identifié dans un flux continu de données d'entrée surveillées, par exemple des conditions spécifiques, des signaux, etc.

Une architecture orientée événement se compose généralement de fournisseurs et de consommateurs d'événements. Les consommateurs d'événements sont abonnés à des gestionnaires d'événements et les fournisseurs publient ces événements dans le gestionnaire. Lorsque le gestionnaire reçoit un événement d'un fournisseur, il le transfère à tous les consommateurs abonnés ou le stocke pour le transférer par la suite.

Un gestionnaire d'événements est une routine de rappel qui fonctionne de manière asynchrone et gère les données d'entrée reçues par un programme (événements). Dans ce contexte, un événement est un élément significatif d'informations de l'application provenant d'un cadre de développement sous-jacent, généralement une boîte à outils d'interface utilisateur ou une routine de données d'entrée. Par exemple, pour une interface utilisateur, les événements sont notamment la frappe, l'activité de la souris, la sélection d'actions ou l'expiration d'un délai. Pour les données d'entrée, les événements sont par exemple l'ouverture ou la fermeture de fichiers et de flux de données, la lecture de données, etc.

Le terme « gestion d'événements » désigne la réception d'un événement provenant d'un fournisseur par un gestionnaire d'événement et les processus qui suivent cette réception.

Les processus de gestion d'événements sont notamment :

• Identifier où un événement doit être transféré ;
• Transférer l'événement ;
• Recevoir l'événement transféré ;
• Prendre une mesure appropriée pour répondre, par exemple consigner l'événement dans un journal, envoyer une routine de correction d'erreur ou de reprise ou encore envoyer un message ;
• Le gestionnaire d'événements peut finir par transférer l'événement à un consommateur d'événements.

Les architectures orientées événement ont l'avantage de permettre de recueillir de manière arbitraire un grand nombre de consommateurs et de producteurs ainsi qu'un certain nombre de gestionnaires pour échanger en continu des informations sur l'état et les réponses. De plus, elles répondent assez rapidement aux événements lorsqu'ils se produisent et fonctionnent bien dans des environnements imprévisibles et asynchrones.

Particularités de la gestion d'événements dans l'API .NET ForexConnect

L'API .NET ForexConnect comprend déjà des interfaces IO2GSessionStatus et IO2GResponseListener pour recevoir des notifications concernant les modifications de statut de session ainsi que des données. Vous pouvez donc utiliser les événements .NET appropriés de l'objet O2GSession au lieu d'appliquer vous-mêmes ces interfaces. Cependant, vous pouvez également les appliquer et les utiliser pour recevoir les notifications de l'objet session après abonnement si cela vous convient mieux.

Notez que tous les gestionnaires d'événements appliqués pour les événements O2GSession sont appelés dans un thread distinct. C'est pourquoi vous devez garder à l'esprit les instructions suivantes :

1. Vous devez toujours fournir un accès à thread sécurisé à toutes les données stockées dans votre application mises à jour par vos gestionnaires d'événements.
2. Vous n'avez pas besoin de synchroniser les appels des gestionnaires d'événements ou de vous soucier d'une nouvelle entrée du gestionnaire d'événements car tous les événements de l'API sont synchronisés dans un thread. Les gestionnaires d'événements sont donc appelés de manière séquentielle.
3. Vous devez gérer tous les événements dès que possible car ceux-ci sont synchronisés dans le thread des gestionnaires par la bibliothèque ForexConnect. Vous pouvez exécuter vos propres threads pour accélérer la gestion d'événements.

Gestion de la durée de vie d'un objet

Vous n'avez pas besoin de gestion de ressources supplémentaires pour les objets obtenus avec l'API .NET ForexConnect. Toutefois, il est recommandé d'utiliser la méthode Dispose() pour tous les objets obtenus qui la mettent en œuvre. Cela vous permet de libérer des ressources inutilisées du système de manière plus efficace. Pour cela, vous pouvez utiliser l'instruction using :

    using (O2GValueMap valuemap = factory.createValueMap())
    {
         //...
    }

Exemple d'application avec l'API .NET ForexConnect

Aperçu

Cet exemple est une simple application console qui utilise l'API .NET ForexConnect. Cette application présente les caractéristiques suivantes :

1. Elle se connecte à un serveur de trading à l'aide des identifiants prédéfinis.
2. Elle récupère les cours de l'instrument EUR/USD.
3. Elle récupère la table des comptes pour l'utilisateur.
4. Elle crée un ordre au marché pour l'instrument EUR/USD lorsque vous saisissez « b » (« buy » – acheter) ou « s » (« sell » – vendre).
5. Elle récupère la table d'ordres et reçoit les notifications de mises à jour de cette table.
6. Elle termine l'exécution de l'application lorsque vous saisissez « q » (« quit » – quitter).

Pour simplifier l'exemple, toute la logique de l'application est implantée dans une classe MyApp.

Vous pouvez télécharger l'intégralité du code source de l'exemple : File:ForexConnect Sample Net.zip

Connexion à un serveur de trading

L'objet principal de l'API .NET ForexConnect est un objet session O2GSession dans l'espace de nom fxcore2. Cet objet représente une session de connexion de l'utilisateur et peut être créé avec une méthode statistique de la classe O2GTransport :

    O2GTransport.createSession();

L'objet O2GSession informe les abonnés de toute modification de l'état de connexion grâce aux événements suivants :

• SessionStatusChanged
• LoginFailed

ou grâce à l'interface de rappel IO2GSessionStatus.

Les données recevant des notifications peuvent être gérées en utilisant les événements O2GSession suivants :

• RequestCompleted
• RequestFailed
• TablesUpdates

ou grâce à l'interface de rappel IO2GResponseListener.

Pour vous connecter à un serveur de trading avec l'API .NET ForexConnect, effectuez les actions suivantes :

1. Créez un objet session.
2. Implantez les gestionnaires pour que les événements de l'objet session reçoivent les notifications de statut des sessions.
3. Appelez le login() de la session et attendez que le processus de connexion soit terminé.
4. Traitez les notifications reçues de modification de statut de session dans onSessionStatusChanged pour gérer l'état du processus de connexion.

Consultez le code source suivant pour obtenir des détails sur l'implantation : '"`UNIQ--toggledisplay-00000006-QINU`"' Notez qu'il faut attendre une notification de la fin de la connexion car l'appel <code>login() est asynchrone. Pour cela, nous utilisons un signal de synchronisation spécial. Lorsque onSessionStatusChanged est appelé, le signal est défini pour reprendre l'exécution du fil après mSyncSessionEvent.WaitOne(5000) dans la méthode run().

Se connecter en choisissant la session de trading

Lorsqu'un compte utilisateur dispose de plusieurs sessions de trading, la connexion a lieu en plusieurs étapes :

1. Appelez la méthode login() de l'objet session avec le nom d'utilisateur, le mot de passe, l'URL de serveur et le nom de base de données spécifiés.

2. Traitez le statut reçu TradingSessionRequested dans le gestionnaire d'événements onSessionStatusChanged. Voici les étapes courantes pour traiter le statut TradingSessionRequested :

2.1. Récupérez la liste des sessions de trading de l'objet O2GSession avec la méthode getTradingSessionDescriptors().

2.2. Proposez une liste de session de trading à l'utilisateur.

2.3. Demandez un code PIN secret à l'utilisateur.

2.4. Définissez l'ID et le PIN de la session de trading en utilisant setTradingSession().

            '"`UNIQ--toggledisplay-00000007-QINU`"'

3. Si setTradingSession réussit, le statut Connected est reçu dans le gestionnaire d'événements onSessionStatusChanged.

Gérer les cours

La gestion des cours comprend les étapes suivantes :

1. Vérifiez que les données sur les cours sont automatiquement demandées lors de la connexion.
   • Si c'est le cas, passez à l'étape 2.
   • Sinon, envoyez une requête pour les cours actuels de tous les instruments.
2. Traitez la réponse.
3. Traitez la mise à jour de certains instruments.

Pour recevoir des notifications des réponses aux requêtes ou des modifications de l'état des objets serveur, vous devez implanter les gestionnaires d'événements et les abonner aux événements appropriés de l'instance O2G2Session.

Pour cela, modifiez la classe MyApp afin qu'elle traite ces événements : '"`UNIQ--toggledisplay-00000008-QINU`"'

Envoyer une requête pour les cours actuels

Selon les paramètres du serveur de trading, les cours actuels de tous les instruments peuvent être reçus automatiquement lors de la connexion ou vous pouvez envoyer une requête explicite pour recevoir ces données. Pour obtenir les cours actuels, vous devez effectuer les actions suivantes :

1. Vérifiez que des offres de prix sont reçues lors de la connexion avec la méthode isTableLoadedByDefault() de l'instance O2GLoginRules.

2. Si c'est le cas, obtenez l'objet réponse des offres déjà reçues en utilisant la méthode getTableRefeshResponse(Offers) de l'instance O2GLoginRules.

Cet objet réponse peut être traité pour extraire les données d'offre. Pour obtenir des lecteurs d'offre et lire les données de réponse, effectuez les actions suivantes :

1. Obtenez la response reader factory grâce à la méthode getResponseReaderFactory() de l'instance objet session.
2. Créez un lecteur grâce à la méthode createOffersTableReader() de l'instance O2GResponseReaderFactory.

3. Si les offres n'ont pas été reçues lors de la connexion, envoyez une requête explicite pour la table d'offres en utilisant la méthode sendRequest() de l'objet session.

Pour créer la requête appropriée :

1. Obtenez la request factory en utilisant la méthode getRequestFactory() de l'objet session.
2. Créez une requête en utilisant la méthode createRefreshTableRequest() de l'instance O2GRequestFactory.

Pour envoyer une requête pour les cours actuels, ajoutez le code source suivant à la méthode run() de notre exemple après la connexion : '"`UNIQ--toggledisplay-00000009-QINU`"'

Dans l'exemple, nous attendons la réception d'une réponse à la requête grâce à un signal de synchronisation. Nous « capturons » le moment adéquat pour commencer à surveiller les variations de cours pour l'instrument EUR/USD. Bien entendu, nous devons définir ce signal après réception des données sur les cours.

Dans notre exemple, nous utilisons un « truc » pour éviter la duplication du code. Comme vous le verrez plus loin, le traitement de la réponse est le même lorsque des données d'offres sont reçues de l'objet O2GLoginRules et lorsque l'on récupère les données avec une requête explicite. C'est pourquoi, pour traiter l'objet réponse reçu de O2GLoginRules, vous pouvez appeler directement le gestionnaire d'événements implanté de l'événement RequestCompleted de l'objet session.

Réception des données sur les cours

Puisque l'appel de sendRequest() est asynchrone, vous devez implanter le gestionnaire d'événements pour l'événement RequestCompleted de l'objet session afin de recevoir une réponse avec des données sur les cours. Ce gestionnaire d'événements étant utilisé pour recevoir les notifications de réponses à toutes les requêtes, vous devez effectuer les actions suivantes :

1. Vérifiez que le type de réponse est GetOffers.
2. Obtenez le lecteur de réponses O2GOffersTableResponseReader en utilisant O2GResponseReaderFactory pour obtenir les données sur les cours à partir de l'objet réponse.
3. Traitez toutes les lignes de la table d'offres à l'aide du lecteur.

Vous devez fournir un accès à thread sécurisé à toutes les offres stockées dans votre application.

Consultez le code source ci-dessous pour voir comment traiter la réception d'une réponse. Pour stocker les cours actuels de l'instrument EUR/USD, les variables adéquates sont définies et un accès à thread sécurisé est mis en place.

'"`UNIQ--toggledisplay-0000000A-QINU`"' Un signal de synchronisation est défini lorsque la réception des données d'offre est terminée. Ce « truc » permet d'attendre la réception des cours actuels dans le fil principal après l'envoi de la requête.

Notre exemple d'application traite l'événement RequestComplete et extrait les prix bid et ask de l'instrument EUR/USD. Ces prix sont stockés dans les variables de classe mEURUSDBid et mEURUSDAsk et des méthodes à fil sécurisé sont implantées pour lire et modifier ces variables.

Réception de mises à jour d'offres

Notez que la notification est reçue dans un thread distinct. Vous devez donc utiliser une lecture et une mise à jour à thread sécurisé des variables qui stockent les données reçues.

Ajoutez le code suivant à MyApp pour traiter la mise à jour du cours de l'instrument EUR/USD :

Le traitement de la table des offres inclut les étapes suivantes :

1. Obtenez O2GResponseReaderFactory à partir de l'objet session.

2. Obtenez un lecteur O2GTablesUpdatesReader en utilisant la factory via la méthode createTablesUpdatesReader.

3. Réalisez une boucle pour énumérer chaque élément de la liste des mises à jour. En effet, les données reçues peuvent contenir des mises à jour pour tout type d'objets, pas uniquement pour la table d'offres. Vous devez donc vérifier la présence du type de table et de mises à jour requis dans chaque élément de la liste de mises à jour.

4. Pour traiter la modification, utilisez la méthode getOfferRow() du lecteur pour récupérer un objet de type O2GOfferRow :

        O2GOfferRow offer = pReader.getOfferRow(i);

Notez que la notification est reçue dans un thread distinct. Vous devez donc utiliser une lecture et une mise à jour à thread sécurisé des variables qui stockent les données reçues.

Ajoutez le code suivant à MyClass pour traiter la mise à jour du cours de l'instrument EUR/USD : '"`UNIQ--toggledisplay-0000000D-QINU`"' Dans notre exemple, nous traitons uniquement les mises à jour des cours de l'instrument EUR/USD et nous stockons leurs dernières valeurs dans les variables mEURUSDBid et mEURUSDAsk. Nous avons utilisé des méthodes à fil sécurisé pour accéder à ces variables.

Création d'ordres

Pour créer un ordre, procédez comme suit :

1. Assurez-vous que vous disposez au moins d'un ID de compte utilisateur et d'un ID d'offre : ces données sont nécessaires pour créer un ordre. Si vous ne les avez pas, demandez-les.

2. Utilisez une instance O2GRequestFactory pour créer O2GValueMap afin de préciser les paramètres de l'ordre.

3. Sur la valuemap, indiquez les paramètres nécessaires pour créer un type d'ordre particulier.

Consultez la page du ForexConnectAPI SDK pour obtenir des détails sur les paramètres de commandes pour créer des ordres.

4. Créez un objet O2GRequest en utilisant O2GRequestFactory pour la valuemap remplie.

5. Démarrez l'exécution de la requête.

6. Recevez la réponse à la requête pour vous assurer que l'exécution est réussie.

Puisque nous avons besoin d'un ID de compte pour notre exemple, récupérons d'abord la table des comptes. La récupération des données contenues dans la table des comptes est similaire à la récupération des données dans la table des offres. Pour simplifier l'exemple, obtenez le premier compte de la liste des comptes utilisateurs et stockez-le dans une variable de classe afin de pouvoir l'utiliser plus tard. '"`UNIQ--toggledisplay-0000000E-QINU`"'

Nous attendons la réponse pour éviter la création d'un ordre avant la récupération de l'ID du compte.

Le meilleur moyen consiste à encapsuler la logique de création de l'ordre dans une méthode distincte de la classe MyApp. Il est également conseillé de traiter la réponse à la requête de création d'ordre dans le gestionnaire d'événements onRequestCompleted afin de vous assurer que l'ordre est créé.

Observez les codes source suivants qui créent un ordre d'achat ou de vente pour l'instrument EUR/USD avec un montant de 100 000. '"`UNIQ--toggledisplay-0000000F-QINU`"'

Notez qu'il existe des classes d'assistant utiles dans le nom d'espace fxcore2.Constants pour remplir l'objet valueMap avec les paramètres de l'ordre.

• Constants.Commands
• Constants.Order

etc.

Vous pouvez conserver l'ID de requête pour traiter la réponse d'une requête particulière uniquement :

    request.RequestId;

Récupérer la table d'ordres

Toutes les informations sur l'état des ordres existants peuvent être récupérées à partir de la table d'ordres.

L'API ForexConnect permet de récupérer la table d'ordres uniquement pour un compte spécifié. Vous devez donc procéder comme suit :

1. Récupérez la table des comptes.
2. Attendez la réception des données sur les comptes.
3. Récupérez la table d'ordres pour chacun des comptes reçus en utilisant createRefreshTableRequestByAccount() de l'instance O2GRequestFactory.
4. Traitez la réponse aux requêtes dans un gestionnaire d'événements de l'événement RequestComplete.
5. Traitez la mise à jour de la table d'ordres dans un gestionnaire d'événements de l'événement TablesUpdates.

Pour simplifier l'exemple, nous prenons l'ID de compte stocké et l'utilisons dans l'exemple de récupération de la table d'ordres.

'"`UNIQ--toggledisplay-00000012-QINU`"' Notez que si vous stockez des données d'ordres, vous devez fournir un accès à fil sécurisé à ces données et une gestion correcte des comptes de référence pour les objets stockés. Dans notre exemple, les données d'ordre ne sont pas stockées, la synchronisation n'est donc pas mise en œuvre.

Finalisation de l'application. Déconnexion

Comme vous le voyez, la méthode stop() de notre classe MyApp libère toutes les ressources système utilisées et désabonne tous les gestionnaires d'événements des événements de session afin qu'ils ne reçoivent plus de notifications. Vous devez appeler logout() avant de finaliser votre application. Vous devez également appeler la méthode Dispose() de l'instance de session avant que _tmain() ne reprenne le contrôle. '"`UNIQ--toggledisplay-00000013-QINU`"'

Gérer les erreurs de requête

Lorsqu'une erreur se produit pendant l'exécution asynchrone d'une requête, le gestionnaire d'événements de l'événement RequestFailed est invoqué. Dans notre exemple, nous gérons l'erreur en plaçant une description de l'erreur dans le flux de sortie de la console et en arrêtant l'application :

        void mSession_RequestFailed(object sender, RequestFailedEventArgs e)
        {
            Console.WriteLine(e.Error);
            stop();
        }

Lancement de l'application exemple

Notre application exemple peut désormais se connecter, récupérer les variations de cours de l'instrument EUR/USD, afficher des informations sur les ordres existants et elle dispose d'une méthode pour créer un ordre au marché ouvert.

Pour lancer l'application exemple à cette étape, nous devons implanter l'utilisation de notre classe MyApp. Pour cela, procédez comme suit :

1. Dans la fonction principale de notre application console, créez une instance de notre classe MyApp.
2. Appelez la méthode run() de l'instance pour vous connecter au serveur de trading et commencer à recevoir des mises à jour pour l'instrument EUR/USD.
3. Fournissez une lecture de la saisie de l'utilisateur pour exécuter des commandes :
   • lorsque « b » est saisi, créez un ordre d'achat ;
   • lorsque « s » est saisi, créez un ordre de vente ;
   • lorsque « q » est saisi, quittez l'application.

    class Program
    {
        static void Main(string[] args)
        {
            MyApp app = new MyApp();
            if (app.run()) //attente de la fin de la connexion et préparations
            {
                char cKey;
                while (true)
                {
                    cKey = (char)Console.Read();
                    if (app.Status == O2GSessionStatusCode.Disconnected) //en cas d'erreur après async, appeler createOrder
                        break;

                    if (cKey == 'q')
                    {
                        app.stop();
                        break;
                    }
                    else if (cKey == 'b')
                        app.createOrder(true);
                    else if (cKey == 's')
                        app.createOrder(false);
                }
            }
        }
    }

La méthode run() de l'exemple prépare l'application au trading. Après la préparation, il renvoie la valeur « true » si tout est correct. Comme vous pouvez le voir, cette méthode appelle toutes les fonctions de l'API de manière asynchrone mais attend leur réponse en utilisant des objets de synchronisation spéciaux. Notez qu'il ne s'agit pas d'une méthode efficace pour utiliser l'API ForexConnect mais qu'elle est simple à comprendre.

N'oubliez pas de saisir un nom d'utilisateur et un mot de passe valides pour un appel de la méthode login().

À présent, vous pouvez créer et exécuter l'exemple. Si vous rencontrez un problème dans la création de l'exemple, veuillez le comparer au code source intégral : File:ForexConnect Sample Net.zip.

Et ensuite ?

Pour obtenir des informations détaillées sur les classes de l'API et sur leurs méthodes, veuillez consulter le ForexConnectAPI SDK.

• Lisez l'article Obtenir les données des tables de trading
• Lisez l'article Utilisation d'une commande batch
• Lisez l'article Créer des ordres OCO
• Lisez l'article S'abonner aux offres d'un instrument et s'en désabonner