Référence API du kit de développement logiciel Intel AppUp® pour C++

SDK Version 2.0  Copyright © 2011 Intel Corporation.  Tous droits réservés.  Document nº : 324249-006US.

Sommaire

À propos de ce document

Public visé

Utilisation de cette référence API

Conventions et symboles

Informations connexes

Historique des révisions

Informations de référence sur les applications

Informations de configuration et de build

Structure des classes

Appel Application Constructor

Exemples de code d'autorisation

Appel GetAuthorizationStatus

Exemple de code d'appel GetAuthorizationStatus

Nettoyage de code

Instrumentation

Appel Begin Event

Appel End Event

API d’achat In-App

Mise à niveau In-App

Appel de déverrouillage In-App

Appel Consumer Identity Service

Rapport d'incident

Structure de classes de rapport d'incident

Détails d'AbstractCrashReport

Détails de DefaultCrashReport

Détails de CallStack

Détails d'AdvancedCrashReport

Exceptions

InitializationException

UnauthorizedException

AdpRuntimeException

AdpWarningException

Exemple de code pour les exceptions

Valeurs retournées/Codes d'erreur

Messages d'erreur pour l'utilisateur final

Informations de référence sur les composants

Règles à observer pour le développement de composants

Appel GetAuthorizationStatus pour les composants

Exemple de code de composant

Information légale

À propos de ce document

Ce document est destiné aux développeurs utilisant le kit de développement logiciel Intel AppUp® 2.0 pour C/C++ afin de développer dans un environnement de développement Microsoft Windows* des applications et des composants ciblés pour un environnement d’exécution Microsoft Windows. Le kit de développement logiciel comprend des bibliothèques de programmation, de la documentation et des exemples de code destinés à aider les développeurs à créer, tester et soumettre des applications C++ afin de les distribuer sur le centre Intel AppUp®.

Remarque : Ce document ne traite que de C++, même si le kit de développement logiciel prend également en charge C. La prise en charge de C est documentée séparément.

Public visé

Ce document est destiné aux développeurs de logiciels expérimentés qui développent des applications et des composants pour le centre Intel AppUp. Il peut s’agir de nouvelles applications ou d'applications existantes portées pour le centre Intel AppUp. Ce kit de développement logiciel prend en charge le développement en environnement de développement Microsoft Windows* 7 ou Windows* XP d'applications ou de composants C++ ciblés pour un environnement d’exécution Microsoft Windows* 7 ou Windows* XP.

Vous trouverez dans les Notes de mise à jour du SDK des informations à propos des éditions et des versions des environnements pris en charge.

Utilisation de cette référence API

Cette référence API contient les sections suivantes :

  • La section À propos de ce document présente le contenu et les conventions utilisées dans le présent document.

  • La section Informations de référence sur les applications documente les appels d'API du SDK pour les applications. Des exemples de code sont fournis, le cas échéant.

  • La section Informations de référence sur les composants documente les appels d'API du SDK pour les composants. Des exemples de code sont fournis, le cas échéant.

Conventions et symboles

Le tableau suivant décrit les conventions utilisées dans ce document.

[cpp]Ce style de police[/cpp]

Indique un élément de syntaxe, mot réservé, mot clé, nom de fichier, une sortie de traitement ou une partie d'exemple de programme. Le texte est en minuscules, sauf si les majuscules sont importantes.

Ce style de police

Indique les caractères exacts que vous saisissez. Également utilisé pour mettre en évidence les éléments de l'interface utilisateur graphique, tels que noms de boutons et de menus ou noms de fichier et étiquettes dans la description d'exemples de programme.

Ce style de police

Indique un espace réservé à un identifiant, une expression, une chaîne, un symbole ou une valeur. Remplacez le ou les espaces réservés par le ou les éléments réels.

Lien hypertexte

Indique un lien hypertexte vers des informations internes ou externes. Utilisez Ctrl+clic de souris pour naviguer.

Remarque :  

Indique un commentaire ou une rubrique connexe importants.

Informations connexes

La prise en main du kit de développement (SDK) pour C++ est expliquée dans le Guide du développeur C++ pour le kit de développement logiciel Intel AppUp®, qui est livré avec le kit de développement logiciel Intel AppUp® pour C/C++. Le SDK est disponible sur le portail de la Zone des développeurs Intel®.

Historique des révisions

Numéro du document

Numéro de révision

Description

Date de révision

324249

001

Version initiale du document pour la prise en charge du SDK C/C++ v1.0

Août 2010

 

002

Mise à jour des informations sur les exceptions

Septembre 2010

 

003

Mise à jour pour prendre en charge la version 1.1 du SDK C/ C++ :

• Ajout des informations sur les messages d'erreur destinés à l'utilisateur final.

• Révision de certains exemples de code.

Novembre 2010

 

004

Mise à jour pour prendre en charge la version 1.1.1 du SDK C/ C++ :

• Ajout des informations sur l’API de mise à niveau In-App.

• Clarifications du contenu existant.

Février 2011

 

005

Mise à jour pour prendre en charge la version 1.1.2 du SDK C/ C++ :

• Mise à jour pour comprendre la version 1.1.2 du débogueur de logiciel Intel AppUp®

Avril 2011

 

006

Mise à jour pour prendre en charge la version 2.0 du SDK C/ C++ :

• Ajout des informations sur l’API de déverrouillage In-App

• Ajout d’informations sur l’API Consumer Identity

Novembre 2011

 

Informations de référence sur les applications

Cette section documente les appels du SDK Elle comporte les sous-sections suivantes :

  • Informations de configuration et de build – documente la configuration générale et les informations de build nécessaires à la création d'applications.

  • Structure des classes – définit la structure des classes de la bibliothèque du SDK.

  • Appel Application Constructor – documente l'appel Application Constructor de la bibliothèque du SDK, lequel est requis pour autoriser les applications du centre Intel AppUp à s'exécuter sur le système du client.

  • Appels d'instrumentation – documente les appels à la bibliothèque du SDK contrôlant les événements d'instrumentation (mesure) des applications.

  • API d’achat In-App – documente les API d’achat In-App de la bibliothèque du SDK permettant de mettre à niveau des applications et d’acheter de nouvelles fonctionnalités d’application.

  • Appel Consumer Identity – documente l’appel d’API permettant d’ouvrir une session dans une application à l’aide d’un fournisseur d’identité tiers tel que Facebook* ou Google* et d’obtenir un jeton d’identité « normalisé », dans le format standard défini par Intel.

  • Rapports d'incident personnalisés – explique comment implémenter des rapports d'incident personnalisés, lorsque la signalisation standard d'incidents n'est pas souhaitable.

  • Exceptions – documente les classes d'exception prises en charge dans le SDK.

  • Codes de retour et d'erreur – documente les codes de retour et d'erreur qui sont pris en charge.

  • Messages d'erreur pour l'utilisateur final – documente les messages d'erreur pouvant être affichés aux utilisateurs finaux.

Des exemples de code sont fournis, le cas échéant. Les informations sur les composants sont couvertes dans la section Informations de référence sur les composants.

Informations de configuration et de build

La liste suivante expose des configurations de base et des informations de build nécessaires à la création d'applications :

          • Vérifiez que Visual Studio a lié de manière statique l'application à la bibliothèque Application Service des runtimes cibles. Ces bibliothèques sont les suivantes :

        Microsoft* Visual Studio* 2008

        Debug Runtime

        Release Runtime

        Adpcored.lib

        Adpcore.lib

        Adpcppfd.lib

        Adpcppf.lib

        Psapi.lib

        Psapi.lib

        Shlwapi.lib

        Shlwapi.lib

        Microsoft* Visual Studio* 2010

        Debug Runtime

        Release Runtime

        Adpcorevc10d.lib

        Adpcorevc10.lib

        Adpcppfvc10d.lib

        Adpcppfvc10.lib

        Psapi.lib

        Psapi.lib

        Shlwapi.lib

        Shlwapi.lib

        • Le chemin des bibliothèques est par défaut : Program Files/Intel/IntelAppUpSDK/Cpp/lib/.

         

        Structure des classes

        La classe Application est, pour les applications, la racine de la hiérarchie des classes dans le framework C++. La classe Component est la racine de la hiérarchie des classes pour les composants dans le framework C++. Vous trouverez plus bas dans la sous-section Informations de référence pour les composants des informations détaillées sur les composants. Comme le montre le schéma ci-dessous, ces deux classes sont basées sur une classe commune Product. Le SDK prend en charge l'extension de la classe Application (héritage) et l'utilisation de la classe Application comme déléguée pour appeler le framework C++. L'extension de la classe Application est l'approche recommandée pour les nouvelles applications. Il n'est possible de créer qu'une seule instance de la classe Application.

         

         

        Appel Application Constructor

        Cet appel est le seul appel requis pour les applications C++ du centre Intel AppUp. Lorsqu'il est invoqué, le constructeur d'application exécute les opérations suivantes : (1) il initialise la bibliothèque du SDK et (2) il autorise l'application via le centre Intel AppUp. Des exceptions sont levées en cas d'échec de ces opérations. En outre, la signalisation par défaut d'incidents est activée, sauf si la signalisation personnalisée est mise en œuvre.

        L'appel Application Constructor doit être placé dans le code d'initialisation de l'application. Le code Header et le code Cleanup doivent également être inclus dans l'application pour prendre en charge cet appel. L'appel Application Constructor doit être suivi d'un gestionnaire d'exceptions.

        Syntaxe

        [cpp]

        const ApplicationId myApplicationID(ApplicationID);

         

        int main( int argc, char** argv ) {

            Application * myApplication = NULL;

            try {

                myApplication  = new Application(myApplicationID);

            }

               // interceptions pour la gestion des exceptions

        }

        [/cpp]

        Paramètres

        myApplication:  le nom de l'objet (l'application)

        ApplicationID:  Le GUID de l'application sous forme de chaîne ou d'entier. Le GUID est composé de quatre nombres entiers longs non signés, comme suit :
         

        ApplicationID(unsigned long l1, unsigned long l2, unsigned long l3, unsigned long l4)

        Voir plus bas la discussion sur l'ID d'application.

        Si l'Application Constructor aboutit, un objet Application est retourné. Sinon, une exception est levée. Les exceptions suivantes sont prises en charge :

        • InitializationException – échec lors d'une tentative d'initialiser le code de la bibliothèque du SDK.

        • UnauthorizedException – échec lors d'une tentative d'autorisation de l'application.

        • AdpRuntimeException – échec dans l'environnement d’exécution général.

        Codes d'erreur (type de données ADP_RET_CODE)

        Valeur

        Signification

        ADP_FAILURE

        L'opération a échoué. Peut également indiquer qu'il a été tenté plusieurs instanciations de l'application.

        ADP_NOT_AVAILABLE

        L'opération a échoué car la bibliothèque du SDK n'était pas disponible. Cela peut se produire si le logiciel du centre Intel AppUp n'est pas installé correctement.

        ADP_NOT_INITIALIZED

        L'opération a échoué car la bibliothèque du SDK n'est pas initialisée. Tout appel d'API effectué avant l'initialisation retourne ce code.

        ADP_INCOMPATIBLE_VERSION

        L'opération a échoué car la version d'API de l'application n'est pas prise en charge par le logiciel actuel du centre Intel AppUp.

        ADP_NOT_AUTHORIZED

        L'exécution de l'application n'est pas autorisée. Les applications peuvent choisir comment répondre, comme empêcher l'exécution d'une application, autoriser l'exécution de l'application pendant une période donnée pour permettre à l'utilisateur d'obtenir une licence, autoriser l'exécution de l'application avec des fonctionnalités limitées, etc.

        ADP_AUTHORIZATION_EXPIRED

        La licence de l'application a expiré. Les applications peuvent choisir comment répondre, comme empêcher l'exécution d'une application, autoriser l'exécution de l'application pendant une période donnée pour permettre à l'utilisateur d'obtenir une licence, autoriser l'exécution de l'application avec des fonctionnalités limitées, etc.

        ADP_TIMEOUT

        L'opération a échoué car la connexion entre le SDK et le logiciel client du centre Intel AppUp a expiré.

          

        ID d'application

        L'ID d'application est un identifiant unique pour les applications du centre Intel AppUp. Il existe deux types de GUID d'application : (1) les ID de débogage et (2) les ID de production. Les ID de débogage sont utilisés pour les tests d'applications. Une fois ceux-ci effectués, vous devez remplacer l'ID de débogage par un ID de production afin de pouvoir télécharger votre application vers le portail de la Zone des développeurs Intel.

        ID de débogage de l'application – pendant le développement, l'ID de débogage permet les tests avec le débogueur de logiciel Intel AppUp. L'ID de débogage est un numéro de 128 bits, exprimé sous forme de chaîne utilisant des constantes prédéfinies. Il existe deux versions de l'ID de débogage :

        • ADP_DEBUG_APPLICATIONID :  utilisé avec le débogueur de logiciel Intel AppUp pour obtenir une réponse ADP_AUTHORIZED. Cela permet de tester et de déboguer la plus grande partie de l'application. La valeur de cet ID de débogage est constituée uniquement par des 1.

        • ADP_EXPIRED_APPLICATIONID :  utilisé avec le débogueur de logiciel Intel AppUp pour obtenir une réponse ADP_AUTHORIZATION_EXPIRED. Cela permet de tester et de déboguer la branche « expirée » de l'application. La valeur de cet ID de débogage est constituée uniquement par des zéros.

        ID de production d'application – Les ID de production s'obtiennent auprès du portail de la Zone des développeurs Intel, ce qui nécessite que vous vous inscriviez en tant que développeur Intel AppUp®. L'ID de production est un nombre de 128 bits composé de quatre nombres entiers au format hexadécimal.

        Notes

        • Le header suivant doit être inclus avant tout appel à Application Constructor : 

         [cpp]

        ///

        #include

        ///

        [/cpp]

        • Nous vous recommandons de tenter une nouvelle procédure d'autorisation si vous recevez une erreur ADP_TIMEOUT à la première tentative.

        • La méthode recommandée pour vérifier le statut d'origine de l'autorisation d'une application à partir du moment où l'appel Application Constructor a été effectué consiste à utiliser une variable locale, créée par le développeur.

        Exemples de code d'autorisation

        Avec un ID de débogage (GUID) fourni par la bibliothèque du SDK

        L'exemple suivant utilise un ID de débogage d'application et il inclut un gestionnaire basique d'exceptions. Le code du header a été préalablement inséré.

         [cpp]

        ///

        const ApplicationId myApplicationID(AdpConstants.ADP_DEBUG_APPLICATIONID);

            /// Remarque : remplacez AdpConstants.ADP_DEBUG_APPLICATIONID par l'ID d'application effectif

            /// une fois que vous l'avez obtenu du portail web de la Zone des développeurs Intel

            /// Pour tester un ID expiré, utilisez AdpConstants.ADP_EXPIRED_APPLICATIONID

        int main( int argc, char** argv ) {

            Application * myApplication = NULL;

            try {

                myApplication = new Application(myApplicationID);

            } catch (AdpException& e) {

                cout << "Exception interceptée dans l'application: " <<

                         e.what() << endl;

            }

        }

        ///

        [/cpp]

        Avec un ID de production

        L'exemple suivant utilise un ID de production d'application et il inclut un gestionnaire basique d'exceptions. Le code du header a été préalablement inséré.

        [cpp]

        ///

        const ApplicationId myApplicationID(0x12341234, 0x56785678, 0x12341234, 0x56785678);

        int main( int argc, char** argv ) {

            Application * myApplication = NULL;

            try {

                myApplication = new Application(myApplicationID);

            }

            /// Ici, le gestionnaire d'exceptions

        }

        ///

        [/cpp]

        Appel GetAuthorizationStatus

        L’appel GetAuthorizationStatus permet de prendre en charge les applications pour les anciennes versions bêta du SDK. Cet appel indique le statut d'origine de l'autorisation du constructeur de l'application à n'importe quel moment une fois que l'appel Application Constructor a été effectué (lire la section Remarques avant de recourir à cet appel).

        Syntaxe

        [cpp]

            static RETURN GetAuthorizationStatus();

        [/cpp]

        Paramètres

        Aucun.

         

        Codes d'erreur (type de données ADP_RET_CODE)

        Valeur

        Signification

        ADP_AUTHORIZED

        L'exécution de l'application est autorisée.

        ADP_NOT_AUTHORIZED

        L'exécution de l'application n'est pas autorisée. Les applications peuvent choisir comment répondre, comme empêcher l'exécution d'une application, autoriser l'exécution de l'application pendant une période donnée pour permettre à l'utilisateur d'obtenir une licence, autoriser l'exécution de l'application avec des fonctionnalités limitées, etc.

        ADP_AUTHORIZATION_EXPIRED

        La licence de l'application a expiré. Les applications peuvent choisir comment répondre, comme empêcher l'exécution d'une application, autoriser l'exécution de l'application pendant une période donnée pour permettre à l'utilisateur d'obtenir une licence, autoriser l'exécution de l'application avec des fonctionnalités limitées, etc.

        ADP_TIMEOUT

        L'opération a échoué car la connexion entre le SDK et le logiciel client du centre Intel AppUp a expiré.

          

        Notes

        • La méthode recommandée pour déterminer le statut d'une autorisation après que l'autorisation initiale a été donnée consiste à utiliser une variable locale créée par le développeur. L’appel GetAuthorizationStatus n'est fourni que pour permettre la prise en charge des anciennes versions bêta du SDK. Le recours à cet appel doit être évité pour les applications utilisant les versions 1.0 et plus récentes du SDK C/C++.

        Exemple de code d'appel GetAuthorizationStatus

        Le code suivant montre comment utiliser l'appel GetAuthorizationStatus.

        [cpp]

        ApplicationId SampleApplication::id(ADP_DEBUG_APPLICATIONID);

        SampleApplication::SampleApplication(int dataIn) : Application(id) {

                // utiliser directement l'ApplicationId à partir de ci-dessus

                this->dataLocal = dataIn;

                // définit la variable membre locale dataLocal à l'aide de la valeur de dataIn

        };

        void SampleApplication::PrintAuthorizationStatus() {

                ADP_RET_CODE ret = Application::GetAuthorizationStatus();

                if( ret  == ADP_AUTHORIZED)

                {

                        wcout << L"L'application est autorisée à s'exécuter" << endl;

                }

                else

                {

                        wcout << L"Statut de l'autorisation de l'application pour "

        << (string) id << ": " << ret << endl;

                }

        };

        int SampleApplication::GetData()

                return dataLocal; //retourne le contenu de la variable membre dataLocal

        };

        [/cpp]

        Nettoyage de code

        Lors de l'arrêt de l'application ou d'un processus, la bibliothèque du SDK doit recevoir l'instruction de relâcher l'objet et de fermer la bibliothèque du SDK. Le code suivant effectue ce nettoyage.
         

        [cpp]

        ///

            if (myApplication != NULL){

                delete myApplication;

        myApplication = NULL;

        }

            return 0;

        ///

        [/cpp]

        Instrumentation

        Le SDK prend en charge les événements d'instrumentation suivants pour mesurer l'utilisation de l'application :

        • Application Begin Event – déclenche l'envoi pour l'application d'un message Begin Event au centre Intel AppUp.

        • Application End Event – déclenche l'envoi pour l'application d'un message End Event au centre Intel AppUp.

        Un enregistrement d'utilisation est généré uniquement lorsqu'un événement de début est suivi par un événement de fin. Un événement de début seul n'entraîne pas la génération d'un enregistrement.

        Appel Begin Event

        Insérez l'appel BeginEvent à l'endroit où vous voulez déclencher l'événement Begin. Il est recommandé de l'insérer dans la même séquence et immédiatement après l'appel Application Constructor. Cela démarre la mesure de l'utilisation de l'application lorsque celle-ci est autorisée pour la première fois et cela permet à l'appel BeginEvent de partager le même gestionnaire d'exceptions que l'appel Application Constructor.

        Syntaxe

        [cpp]

        try {

            myApp->BeginEvent();

            }

        [/cpp]

        Paramètres

        myApp:  le nom de l'objet (l'application)

        Si l'appel BeginEvent réussit, un message Begin Event est déclenché. Sinon, une exception est levée. L'exception suivante est prise en charge :

        • AdpRuntimeException – échec dans l'environnement d’exécution général.

          

        Codes d'erreur (type de données ADP_RET_CODE)

        Valeur

        Signification

        ADP_FAILURE

        L'opération a échoué.

        ADP_NOT_INITIALIZED

        L'opération a échoué car la bibliothèque du SDK n'est pas initialisée. Tout appel d'API effectué avant l'initialisation retourne ce code.

        ADP_NOT_AUTHORIZED

        L'exécution de l'application n'est pas autorisée. Les applications peuvent choisir comment répondre, comme empêcher l'exécution d'une application, autoriser l'exécution de l'application pendant une période donnée pour permettre à l'utilisateur d'obtenir une licence, autoriser l'exécution de l'application avec des fonctionnalités limitées, etc.

          

        Notes

        • Tout appel BeginEvent doit être précédé d'un appel Application Constructor réussi, faute de quoi une exception est levée.

        • Nous vous recommandons de tenter une nouvelle séquence d'autorisation si vous recevez un code ADP_FAILURE (dans les situations critiques) à la première tentative. Cela peut rétablir une session valide avec le logiciel client du centre Intel AppUp.

        Exemple de code

        L'exemple suivant montre comment utiliser l'appel BeginEvent. Un gestionnaire basique d'exceptions est utilisé.

        [cpp]

        #include "adpcppf.h"

        #include

        int main( int argc, char** argv ) {

            try {

                Application *myApp = new Application(ApplicationId::DEBUG_ID );

                myApp->BeginEvent();

            }

            catch (AdpErrorException& e) {

                    // Le code de gestion des exceptions

                    wcout << L"Exception d'initialisation interceptée dans l'application: " <<

                         e.what() << endl;

            }

            /// Ici, le code de l'application

        }

        [/cpp]

         

        Appel End Event

        Les appels End Event doivent être précédés d'appels Begin Event sous peine qu'une exception soit levée. L'appel EndEvent est normalement utilisé dans la séquence d'arrêt de l'application.

        Syntaxe

        [cpp]

        try {

            myApp->EndEvent();

        }

        [/cpp]

        Paramètres

           myApp:  le nom de l'objet (l'application)

        Si l'appel EndEvent réussit, un message End Event est déclenché. Sinon, une exception est levée. L'exception suivante est prise en charge :

        • AdpRuntimeException – échec dans l'environnement d’exécution général.

        • AdpWarningException – une condition d'avertissement a été détectée, par exemple, absence d'appel BeginEvent préalable .

          

        Codes d'erreur (type de données ADP_RET_CODE)

        Valeur

        Signification

        ADP_FAILURE

        L'opération a échoué.

        ADP_NOT_INITIALIZED

        L'opération a échoué car la bibliothèque du SDK n'est pas initialisée. Tout appel d'API effectué avant l'initialisation retourne ce code.

        ADP_NOT_AUTHORIZED

        L'exécution de l'application n'est pas autorisée. Les applications peuvent choisir comment répondre, comme empêcher l'exécution d'une application, autoriser l'exécution de l'application pendant une période donnée pour permettre à l'utilisateur d'obtenir une licence, autoriser l'exécution de l'application avec des fonctionnalités limitées, etc.

        ADP_NO_APP_BEGIN_EVENT

        L'opération a échoué car un appel d'événement de fin a été lancé sans appel d'événement de début préalable. Un appel Begin Event doit précéder un appel End Event dans l'application.

          

        Notes

        • Tout appel EndEvent doit être précédé d'un appel BeginEvent sous peine que soit levée une exception d'avertissement.

        • Nous vous recommandons de tenter une nouvelle séquence d'autorisation si vous recevez un code ADP_FAILURE (dans les situations critiques) à la première tentative. Cela peut rétablir une session valide avec le logiciel client du centre Intel AppUp.

        Exemple de code

        L'exemple suivant montre comment utiliser l'appel EndEvent. Le code déclenche un message End Event et inclut un gestionnaire d'exceptions pour AdpRuntimeException et AdpWarningException.

         [cpp]

           // Ici, le code de l'application

            try {

                myApp->EndEvent();

            }

            catch (AdpRuntimeException& e) {

                    // Le code de gestion des erreurs EndEvent

                    wcout << L"Exception EndEvent interceptée dans l'application:

                         " << e.code() << endl;

            }

            catch (AdpWarningException& e) {

                    // Le code de gestion des avertissements EndEvent

                    wcout << L"Avertissement EndEvent intercepté dans l'application:

                         " << e.code() << endl;

            }

           // Ici, le code de l'application

        [/cpp]

        API d’achat In-App

        La bibliothèque du SDK Intel AppUp fournit une famille d’API prenant en charge des fonctions comme la mise à niveau et l’achat In-App d’applications, etc. Lorsque les appels d’API appropriés sont inclus dans les applications, les utilisateurs finaux peuvent mettre à niveau leur application, activer des fonctionnalités supplémentaires, des niveaux de jeu, etc., depuis l'application. Les API prises en charge et leurs utilisations typiques sont les suivantes :

        Mise à niveau In-App

        La bibliothèque du SDK Intel AppUp fournit un appel d'API qui autorise la mise à niveau vers une version ultérieure désignée d'une application. Une utilisation courante de cet appel de mise à niveau depuis l'application est la prise en charge de scénarios tels que celui où un utilisateur passe de la version gratuite d'une application à une version premium. Lorsqu'il est invoqué, l'appel passe l'ID de l'application cible au logiciel du centre Intel AppUp. Le logiciel du centre Intel AppUp offre alors la mise à niveau à l'utilisateur final. Si l'utilisateur accepte l'offre, le logiciel du centre Intel AppUp installe la version cible de l'application (en plus de la version originale). Si l'utilisateur la refuse, la version existante de l'application est conservée et fonctionne normalement.

        Syntaxe

            app->Upgrade(TargetApplicationId);

        Paramètres

        app:  le nom de l'objet application

        TargetApplicationId :  GUID de production d'application (voir plus bas la section consacrée à l'ID d'application cible).

        Si l’autorisation de mise à niveau est accordée, l’application peut continuer (le logiciel du centre Intel AppUp démarre et effectue habituellement la mise à jour). Sinon, une exception est levée 

        • AdpRuntimeException – échec dans l'environnement d’exécution général.

         

        Codes d'erreur (type de données ADP_RET_CODE)

        Valeur

        Signification

        ADP_FAILURE

        L'opération a échoué. Peut également indiquer qu'il a été tenté plusieurs instanciations de l'application.

        ADP_NOT_INITIALIZED

        L'opération a échoué car la bibliothèque du SDK n'est pas initialisée. Tout appel d'API effectué avant l'initialisation retourne ce code.

        ADP_NOT_AUTHORIZED

        L'exécution de l'application n'est pas autorisée. Les applications peuvent choisir comment répondre, comme empêcher l'exécution d'une application, autoriser l'exécution de l'application pendant une période donnée pour permettre à l'utilisateur d'obtenir une licence, autoriser l'exécution de l'application avec des fonctionnalités limitées, etc.

         

        ID de l'application cible

        L'ID d'application est un identifiant unique pour les applications du centre Intel AppUp. L'appel In-Application Upgrade utilise un ID de production d'application qui représente l'application cible. Il n'est pas nécessaire que cet ID de production d'application soit l'ID de production utilisé pendant le développement. Mais l'ID de production de l'application doit être inclus avant l'envoi de votre application vers le portail de la Zone des développeurs Intel. Pour le rendre plus facile à mémoriser, il est indiqué d'utiliser pendant le développement l'ID de production de l'application comme application cible.

        Notes

        • Nous vous recommandons de tenter une nouvelle procédure d'autorisation si vous recevez une erreur ADP_FAILURE à la première tentative.

        • L'application cible doit être : (1) déjà validée et présente dans le centre Intel AppUp ou (2) soumise conjointement à l'application originale pour validation.

        Exemple de code

        L'exemple suivant montre l'appel In-Application Upgrade avec un ID de production d'application et des gestionnaires d'exceptions d'avertissement. L'exemple comporte des lignes supplémentaires de code permettant d'utiliser une interface graphique utilisateur avec des boutons et une fenêtre de message.

         [cpp]

             try {

                m_pADPApplication->Upgrade(0x11111111,0x22222222,0x33333333,0x44444444);

                CWnd* pWnd = GetDlgItem(IDC_AdpStatus);

                pWnd->SetWindowText(_T("Upgrading Application..."));

            }

             catch (AdpRuntimeException& e) {

                CString eMsg;

                CWnd* pWnd = GetDlgItem(IDC_AdpStatus);

                eMsg.FormatMessage( _T("Une exception d'exécution ADP a été interceptée dans l'application avec

                    le code d'exception: %1!ld!") , e.code());

                MessageBox(eMsg, _T("Message de l'exception"));

                AfxMessageBox(eMsg, MB_OK , 0);

                pWnd->SetWindowText(eMsg);

            }

             catch (AdpWarningException& e) {

                CString eMsg;

                CWnd* pWnd = GetDlgItem(IDC_AdpStatus);

                eMsg.FormatMessage( _T("Une exception d'avertissement ADP a été interceptée dans l'application avec

                    le code d'exception: %1!ld!") , e.code());

                MessageBox(eMsg, _T("Message de l'avertissement"));

                AfxMessageBox(eMsg, MB_OK , 0);

                pWnd->SetWindowText(eMsg);

            }

         [/cpp]

        Déverrouillage In-App

        La bibliothèque du kit de développement logiciel Intel AppUp fournit une API permettant aux applications Intel AppUp® de recevoir des paiements pour des capacités pré-intégrées dans l’application, une fois que l’application a été installée et utilisée par l’utilisateur final.

        Cette API est souvent utilisée, par exemple, pour déverrouiller des niveaux avancés d’un jeu. Par exemple, un utilisateur final installe une application de jeu et peut jouer les trois premiers niveaux gratuitement mais pour accéder aux niveaux supérieurs, l’utilisateur doit les acheter. L’API In-App Unlocking Intel AppUp® ne prend pas en charge le téléchargement de nouveaux contenus. Elle permet uniquement de déverrouiller les capacités existantes de l’application. Dans cette version, l’API ne prend en charge que les articles non consommables (comme les niveaux de jeu) et ne prend pas en charge les articles consommables (comme l’achat de 1 000 missiles supplémentaires). Vous pouvez simuler des articles consommables en utilisant un groupe d’articles non consommables, mais cela exige des efforts supplémentaires et n’entre pas dans le cadre de ce document.

        L’application invite l’utilisateur à acheter un article pré-intégré. Si l’utilisateur décide d’acheter l’article, les appels suivants sont traités :

        1. L’application lance un appel à l’API In-App Unlocking Intel AppUp®, la demande est envoyée au centre Intel AppUp.

        2. Le centre Intel AppUp présente à l’utilisateur une boîte de dialogue de confirmation avec le titre de l’article, son prix et la devise.

        3. L’utilisateur confirme l’achat. Si l’utilisateur n’est pas connecté, les événements suivants se produisent :

          1. Le centre Intel AppUp présente la boîte de dialogue d’ouverture de session AppUp à l’utilisateur.
             Si l’utilisateur n’a pas encore fourni ses informations de facturation, le centre Intel AppUp réoriente l’utilisateur vers la page permettant à celui-ci de fournir ses informations de facturation.

          2. Une fois que l’utilisateur a ouvert une session et fourni ses informations de facturation, le centre Intel AppUp soumet une demande d’achat au service de gestion d’Intel AppUp.

        4. Une fois que l'achat est terminé et confirmé, l'utilisateur final peut continuer à utiliser l'application, l'article acheté étant maintenant activé.

        Les classes de déverrouillage In-App suivantes sont incluses dans le framework C++ du SDK.

        Détails sur les classes d’application

        Application : représente l’instance de l’application Intel AppUp.

        Méthodes

        AppItemIF* Application::CreateAppItem(const wchar_t* id, const wchar_t* locale, bool bRefresh = false) throw(...)

        Créez une instance AppItemIF qui représente un article d’application. L’application doit avoir été autorisée avant que cette API puisse être appelée.

        Paramètres

        id: ID de l’article d’application spécifié par le développeur

        locale: Emplacement de l’application

        bRefresh: facultatif, une balise booléenne qui, lorsqu’elle est définie, force la mise à jour des métadonnées de l’article. La valeur par défaut est Faux.

        Valeurs retournées

        • InAppItemException – L'élément basé sur les paramètres n'a pas été créé.
        • AdpRuntimeException – échec dans l'environnement d’exécution général.

        Remarques

        L’application doit avoir été autorisée avant que cette fonction puisse être appelée.

        Cette fonction est active uniquement lorsque l’utilisateur est connecté et peut être appelée pour obtenir une objet AppItemIF qui est utilisé pour acheter une article d’application.

        Codes d’erreur

        Valeur

        Signification

        ADP_INVALID_DEVID

        L’ID fourni par le développeur n’est pas valide.

        ADP_INVALID_LOCALE

        L’emplacement n’est pas valide.

        ADP_OFFLINE

        L’appareil n’est pas en ligne

        ADP_APP_NOTAVAILABLE

        Cette application n'est pas disponible.

        ADP_ITEM_NOTAVAILABLE

        L’article d’application demandé n'est pas disponible.

        ADP_USER_NOTIDENTIFIED

        L’utilisateur n’est pas identifié.

        ADP_TIMEOUT

        Expiration de l’opération.

        ADP_FAILURE

        Une erreur générale s’est produite, qui n’est pas couverte par les codes d’erreur ci-dessus.

         

        bool Application::IsAppItemPurchased(const wchar_t* id)

        Vérifier si l’article d’application a bien été acheté. L’application doit avoir été autorisée avant que cette API puisse être appelée.

        Paramètres

        id: ID de l’article d’application spécifié par le développeur

        Valeurs retournées

        La valeur retournée est Vrai si l’article a été acheté. Sinon, la valeur retournée est Faux.

        Remarques

        L’application doit avoir été autorisée avant que cette API puisse être appelée.

        Cette fonction est opérationnelle que l’appareil soit connecté ou non, elle peut être utilisée pour déterminer si un article d’application a été acheté ou non.

        Détails sur les classes AppItemIF

        AppItemIF: Classe abstraite qui représente un article d’application.

        Méthodes

        virtual const wstring AppItemIF::GetProperty(const wchar_t*  propId)

        Retourne la valeur de la propriété de l’article demandée. La valeur retournée peut être une chaîne vide.

        Paramètres

        propId: Nom de la propriété. Les valeurs valides sont définies dans /Cpp/Include/adpcore.h sous forme de macros : : ITEM_GUID, ITEM_LOCALE, ITEM_ID, ITEM_TITLE, ITEM_DESC, ITEM_PRICE, ITEM_CURRENCY, ITEM_TOKEN

        Valeur retournée

        La valeur de la propriété demandée.

         

        virtual wstring AppItemIF::GetSignedToken()

        Retourne le jeton signé de la propriété d’achat demandée. La valeur retournée peut être une chaîne vide.

        Paramètres

        Aucun

        Valeur retournée

        Le jeton signé de cet article d’application.

         

        virtual bool AppItemItem::IsPurchased()

        Vérifie si l’article a bien été acheté.

        Paramètres

        Aucun

        Valeurs retournées

        La valeur retournée est Vrai si l’article a été acheté. Sinon, la valeur retournée est Faux.

         

        virtual bool AppItemIF::Purchase(const wchar_t* price, const wchar_t* currency) throw(...)

        Acheter un article d’application. Le prix et la devise fournis sont comparés aux métadonnées de l’article correspondant par le service de gestion du centre Intel AppUp. L’opération échoue si les valeurs ne correspondent pas.

        Paramètres

        price  Prix de l’article à acheter

        Currency Devise de l’article à acheter

        Valeurs retournées

        • InAppItemException – l'opération a échoué.
        • AdpRuntimeException – échec dans l'environnement d’exécution général.

        Remarques

        Le prix et la devise fournis sont comparés aux métadonnées de l’article correspondant par le service de gestion du centre Intel AppUp. L’opération échoue si les valeurs ne correspondent pas.

        Pour les paramètres de prix et de devise, nous vous recommandons d’utiliser les valeurs retournées par la fonction AppItemIF::GetProperty(). Si la valeur de devise ne correspond pas aux informations de facturation de l’utilisateur, l’opération échoue.

        Codes d’erreur

        Valeur

        Signification

        ADP_INVALID_PRICE

        Prix non valide

        ADP_INVALID_CURRENCY

        Devise non valide

        ADP_OFFLINE

        Le service de gestion d’Intel AppUp n’est pas en ligne

        ADP_USERCANCEL

        L’utilisateur a annulé l’achat

        ADP_APP_NOTAVAILABLE

        L’application n'est pas disponible

        ADP_ITEM_NOTAVAILABLE

        L’article d’application demandé n'est pas disponible

        ADP_PRICE_CURRENCY_MISMATCH

        Le prix ou la devise ne correspondent pas

        ADP_ALREADY_PURCHASED

        L’article d’application demandé a déjà été acheté

        ADP_USER_NOTIDENTIFIED

        L’utilisateur n’est pas identifié

        ADP_TIMEOUT

        Expiration de l’opération

        Exemple de code d’appel de déverrouillage In-App

        L’exemple suivant montrant comment créer et acheter habituellement un article d’application.

        [cpp]

        #include "adpcppf.h"

        #include

        using namespace std;

        int _tmain(int argc, _TCHAR* argv[])

        {

          wcout << L"Version de l’API ADP : " << ADP_API_VERSION <<endl;< p="">

          Intel::Adp::Application *pInAppUnlockingSampleApp = NULL;

          AppItemIF *pItemIf = NULL;

           try {

            pInAppUnlockingSampleApp = new Application(ADP_DEBUG_APPLICATIONID);

            // call Application::IsAppItemPurchased(const wchar_t* id)

            // pour vérifier si l’article InAppItem est acheté

            if(pInAppUnlockingSampleApp->IsAppItemPurchased(L"level3"))

              wcout << L"level3 a déjà été acheté." << endl;

            else

              wcout << L"level3 n’a pas encore été acheté." << endl;

            //changez l’id du développeur et son emplacement ici pour ajuster les métadonnées de l’article.

            pItemIf = pInAppUnlockingSampleApp->CreateInAppItem(L"level3", L"en-US", true);

            wcout << L"La création de l’article d’application a réussi" << endl;

            wcout << L"GUID de l’article: "<
        GetProperty(ITEM_GUID)<< endl;

            wcout << L"Emplacement de l’article: "<
        GetProperty(ITEM_LOCALE)<< endl;

            wcout << L"ID de l’article fourni par le développeur: "<
        GetProperty(ITEM_ID)<< endl;

            wcout << L"ItemName court de l’article: "<
        GetProperty(ITEM_DESC)<< endl;

            wcout << L"Prix de l’article: "<
        GetProperty(ITEM_PRICE)<< endl;

            wcout << L"Devise de l’article: "<
        GetProperty(ITEM_CURRENCY)<< endl;

            wcout << L"L’obtention des propriétés de l’article a réussi" << endl;

            wcout << L"L’article "<< (pItemIf->IsPurchased() ? "" : "n’a pas ") <<"été acheté"<< endl;

            //changez le prix et la devise pour ajuster les métadonnées de votre article

            bool bPurchased = pItemIf->Purchase(pItemIf->GetProperty(ITEM_PRICE).c_str(), pItemIf->GetProperty(ITEM_CURRENCY).c_str());

            if(bPurchased)

            wcout << L"L’achat de l'article a réussi" <<endl;< p="">

            wcout << L"Jeton de l’article:" << pItemIf->GetSignedToken() << endl;

            wcout << L"L’obtention du jeton de l’article a réussi" << endl;

            }

            catch (Intel::Adp::InitializationException& e) {

            wcout << L"Exception Initialisation interceptée dans l'application avec le code d’exception: " << e.code() << endl;

            }

          catch (Intel::Adp::UnauthorizedException& e) {

            wcout << L"Exception Autorisé interceptée dans l'application avec le code d’exception: " << e.code() << endl;

          }

          catch (Intel::Adp::AdpRuntimeException& e) {

            wcout << L"Exception Runtime interceptée dans l'application avec le code d’exception: " << e.code() << endl;

          }

          catch (Intel::Adp::InAppItemException& e) {

            wcout << L"Exception InAppItem interceptée dans l'application avec le code d’exception: " << e.code() << endl;

          }

          //supprimez le pointeur de l’article d’application

          if(pItemIf)

          {

          delete pItemIf;

          pItemIf = NULL;

          }

          //supprimez le pointeur de l’application

          if(pInAppUnlockingSampleApp != NULL){

            delete pInAppUnlockingSampleApp;

            pInAppUnlockingSampleApp = NULL;

          }

           return 0;

        }

        [/cpp]

        Appel Consumer Identity Service

        L’API Consumer Identity Service permet à l’application d’ouvrir une session dans une application avec un fournisseur d’identité tiers tel que Facebook* ou Google*. Une fois que la session est ouverte, l’application peut obtenir le jeton d’identité « normalisé », dans le format standard défini par Intel.

        L’utilisation typique de cette API comprend les étapes suivantes :

        1. Invoquer la fonction GetIdentityProviders pour obtenir les fournisseurs d’identité pris en charge et les afficher dans la page d’ouverture de session de l’application.

        2. L’utilisateur final sélectionne un fournisseur d’identité pour ouvrir une session

        3. L’application invoque la fonction Login pour ouvrir la page d’ouverture de session du fournisseur d’identité dans le navigateur par défaut, puis attend qu’une fonction de rappel soit invoquée par Consumer Identity Service.

        4. L’utilisateur final rempli ses identifiants de compte et accorde des droits d’accès à l’application

        5. La fonction de rappel est invoquée pour notifier l’application que le jeton normalisé est prêt.

        6. L’application appelle la fonction GetIdentityToken pour obtenir le jeton normalisé.

        REMARQUE : L’application cible doit être validée et se trouver dans le centre Intel AppUp

        Détails sur les classes IdentityProvider

        IdentityProvider: Fournit les API permettant de construire un objet Identity Provider et envoie une requête pour obtenir les propriétés du fournisseur d’identité.

        Constructor

        Méthodes

        std:wstring GetName() const

        Valeurs retournées

        Le nom du fournisseur d’identité.

         

        std:wstring GetIconURI() const

        Valeurs retournées

        L’URI de l’icône du fournisseur d’identité.

        Détails sur les classes IdentityToken

        IdentityToken: Fournit les API permettant de construire un objet Identity Token et envoie une requête pour obtenir les propriétés d’un jeton d’identité normalisé.

        Constructor

        Méthodes

        std:wstring GetFirstName() const

        Valeurs retournées

        Le prénom de l’utilisateur final.

         

        std:wstring GetLastName() const

        Valeurs retournées

        Le nom de l’utilisateur final.

         

        std:wstring GetEmail() const

        Valeurs retournées

        L’adresse de courriel de l’utilisateur final.

         

        std:wstring GetTimestamp() const

        Valeurs retournées

        L’horodatage du jeton.

         

        std:wstring GetExpDate() const

        Valeurs retournées

        La date d’expiration du jeton.

         

        std:wstring GetIdentity() const

        Valeurs retournées

        L’identité du jeton.

         

        std:wstring GetIdentityProvider() const

        Valeurs retournées

        L’identité publique du fournisseur d’identité.

         

        std:wstring GetToken() const

        Valeurs retournées

        Le jeton normalisé au format XML.

        Détails sur les classes ConsumerIdentityService

        ConsumerIdentityService: Fournit les API permettant d'obtenir la liste des fournisseurs d'identité, de commencer une session d'ouverture de session et d'obtenir le jeton d'identité normalisé.

        Constructor

        L’objet Consumer Identity Service peut être obtenu uniquement par la méthode définie dans la classe Application : ConsumerIdentityService* GetConsumerIdentityService() const.

        Il n’existe qu’une seule instance d'objet Consumer Identity Service dans le cadre d’un processus. Si une fonction est appelée plusieurs fois, le même pointeur vers l’objet Consumer Identity Service est retourné.

        L’application NE DOIT PAS supprimer la référence à ce pointeur car sa référence sera supprimée par le destructeur de la classe Application.

        Valeurs retournées

        Si la fonction réussit, la valeur retournée est l’objet du service Consumer Identity Service. Sinon, l’exception suivante est levée :

        • UnauthorizedException – Échec de la tentative d’appel de cette fonction avant que l’objet Application soit construit.

        Codes d’erreur

        Valeur

        Signification

        ADP_NOT_AVAILABLE

        ADP_NOT_AVAILABLE

        ADP_FAILURE

        L'opération a échoué. Peut également indiquer qu'il a été tenté plusieurs instanciations de l'application.

        ADP_NOT_INITIALIZED

        L'opération a échoué car la bibliothèque du SDK n'est pas initialisée. Tout appel d'API effectué avant l'initialisation retourne ce code.

        ADP_INCOMPATIBLE_VERSION

        L'opération a échoué car la version d'API de l'application n'est pas prise en charge par le logiciel actuel du centre Intel AppUp.

        ADP_NOT_AUTHORIZED

        L'exécution de l'application n'est pas autorisée. Les applications peuvent choisir la manière de répondre : empêcher une application de s'exécuter ; autoriser l'application à s'exécuter pendant une période de grâce pour permettre à l'utilisateur d'obtenir une licence ; autoriser l'application à s'exécuter avec des fonctionnalités limitées.

        ADP_AUTHORIZATION_EXPIRED

        La licence de l'application a expiré. Les applications peuvent choisir la manière de répondre : empêcher une application de s'exécuter ; autoriser l'application à s'exécuter pendant une période de grâce pour permettre à l'utilisateur d'obtenir une licence ; autoriser l'application à s'exécuter avec des fonctionnalités limitées.

        ADP_TIMEOUT

        L'opération a échoué car la connexion entre le SDK et le logiciel client du centre Intel AppUp a expiré.

        Méthodes

        std::vector<:adp::consumeridentity::identityprovider> GetIdentityProviders()

        Valeurs retournées

        Si la fonction réussit, la valeur retournée est la liste des objets des fournisseurs d’identité pris en charge. Sinon, une exception est levée. Les exceptions suivantes sont prises en charge :

        • InvalidIdentityProviderException – Échec dû à des données de fournisseur d’identité incomplètes.

        • AdpRuntimeException – Échec de la tentative d’appel de cette fonction avant que l’objet Consumer Identity Service soit construit.

        Codes d’erreur

        Valeur

        Signification

        ADP_CI_INVALID_IDENTITY_PROVIDER

        Données de fournisseur d’identité non valides ou incomplètes.

        ADP_FAILURE

        Une erreur générale se produit, qui n’est pas couverte par les codes d’erreur ci-dessus.

         

        void Login(const Intel::Adp::ConsumerIdentity::IdentityProvider& identityProvider, LoginCallbackProc pCallbackProc, void* pParameter, bool bringAppToForeground = true)

        Commencer une nouvelle session d’ouverture de session. Cette fonction ouvre un nouvel onglet dans le navigateur par défaut et navigue jusqu’à la page d’ouverture de session du fournisseur d’identité.

        Les API Consumer Identity Service prennent en charge les méthodes synchone et asynchrone permettant d’obtenir le jeton d’identité normalisé. Pour utiliser cette API de manière synchrone, passez NULL au paramètre pCallbackProc. Pour utiliser cette API de manière asynchrone, passez un pointeur valide à la fonction de rappel du paramètre pCallbackProc.

        Cette API permet à l’application de mettre sa fenêtre principale au premier plan avant que la valeur GetIdentityToken soit retournée. Pour activer cette fonctionnalité, passez true au paramètre bringAppToForeground. Pour désactiver cette fonctionnalité, passez false au paramètre bringAppToForeground.

        Comme une seule session d’ouverture de session est autorisée dans un processus donné, pour commencer une nouvelle session d’ouverture de session, vous devez attendre que la session d’ouverture de session précédente soit terminée, ou appeler explicitement la fonction Annuler, avant d’appeler à nouveau cette fonction.

        Paramètres

        identityProvider: La référence de l’objet du fournisseur d’identité auquel l’utilisateur final a choisi de se connecter.

        pCallbackProc: Le pointeur vers la fonction définie par l’utilisateur devant être utilisée pour notifier l’application que la session d’ouverture de session est terminée. Pour davantage d’informations sur la fonction de rappel, voir LoginCallbackProc.

        pParameter: Un pointeur vers une variable définie par l’application devant être passée à la fonction de rappel. Si pCallbackProc est NULL, ce paramètre est ignoré.

        bringAppToForeground (facultatif): Indique si l’application veut que le SDK mette la fenêtre principale au premier plan une fois que la session d’ouverture de session est terminée.

        Valeurs retournées

        Si la fonction réussit, un nouvel onglet du navigateur par défaut s’ouvre sur la page d’ouverture de session du fournisseur d’identité. Sinon, une exception est levée. Les exceptions suivantes sont prises en charge :

        • InvalidOperationException – Échec de la tentative d’appel de cette fonction avant que la session d’ouverture de session précédente soit terminée ou annulée.

        • AdpRuntimeException – Échec de la tentative d’appel de cette fonction avant que l’objet Consumer Identity Service soit construit.

        Codes d’erreur

        Valeur

        Signification

        ADP_CI_INVALID_OPERATION

        Vous avez commencé une session d’ouverture de session avant que la session d’ouverture de session précédente soit terminée ou annulée

        ADP_FAILURE

        Une erreur générale se produit, qui n’est pas couverte par le code d’erreur ci-dessus.

         

        void cancel()

        Annuler la session d’ouverture de session actuelle. L’application doit appeler cette fonction pour annuler la session d’ouverture de session actuelle avant de placer un nouvel appel à la fonction Login pour commencer une nouvelle session d’ouverture de session.

        Aucune exception n’est levée, même si vous appelez cette fonction une fois que la session d’ouverture de session actuelle est terminée ou si vous appelez cette fonction plusieurs fois.

        Valeurs retournées

        Si la fonction réussit, la session d’ouverture de session actuelle est annulée. Sinon, une exception est levée. Les exceptions suivantes sont prises en charge :

        • AdpRuntimeException – Échec de la tentative d’appel de cette fonction avant que l’objet Consumer Identity Service soit construit.

        Codes d’erreur

        Valeur

        Signification

        ADP_FAILURE

        Une erreur générale s’est produite.

         

        Intel::Adp::ConsumerIdentity::IdentityToken GetIdentityToken()

        Cette API bloque le thread d’appel d’une application jusqu’à ce que le jeton d’identité normalisé soit reçu du service Intel Identity Service, ou jusqu’à ce qu’une erreur se produise.

        Valeurs retournées

        Si la fonction réussit, une nouvelle instance de jeton d’identité normalisé est construite et retournée. Sinon, une exception est levée. Les exceptions suivantes sont prises en charge :

        • UserAccessDenyException – L’utilisateur final n’a pas accordé de droits d’accès à l’application.

        • RequestTimeoutException – L’utilisateur final n’a pas terminé l'ouverture de session dans les délais impartis (la valeur par défaut est de 300 secondes).

        • InvalidIdentityTokenException – Données de jeton d’identité normalisé non valides ou incomplètes obtenues du service Intel Identity Service.

        • InvalidIdentityTokenSignatureException – L’intégrité de la signature du jeton d’identité normalisé n’a pas été vérifiée.

        • InvalidOperationException – Échec dû à un appel à cette fonction avant d’appeler la fonction Login().

        • AdpRuntimeException – Échec dû à une tentative d’appel à cette fonction avant que l’objet Consumer Identity Service soit construit.

        Codes d’erreur

        Valeur

        Signification

        ADP_CI_USER_ACCESS_DENY

        L’utilisateur final n’a pas accordé de droits d’accès à l’application

        ADP_CI_REQUEST_TIMEOUT

        L’utilisateur final n’a pas terminé l’ouverture de session dans les délais impartis (le délai par défaut est de 300 secondes)

        ADP_CI_INVALID_IDENTITY_TOKEN

        Données de jeton d’identité non valides ou incomplètes

        ADP_CI_INVALID_IDENTITY_TOKEN_SIGNATURE

        La vérification de la signature du jeton d’identité normalisé a échoué

        ADP_CI_INVALID_OPERATION

        Cette fonction a été appelée avant une fonction Login

        ADP_FAILURE

        Une erreur générale se produit, qui n’est pas couverte par les codes d’erreur ci-dessus

        Détails de la fonction LoginCallbackProc

        LoginCallbackProc: Espace réservé à une fonction définie par l’application qui sert de fonction de rappel, utilisé par Consumer Identity Service pour notifier l’application que la session d’ouverture de session est terminée.

        Syntaxe

        void LoginCallbackProc(void* pParameter)

        Cette fonction est appelée par Consumer Identity Service lorsque la session d’ouverture de session s’est terminée avec succès ou si une erreur s’est produite. Une fois que cette fonction est invoquée, l’application doit appeler la fonction ConsumerIdentityService::GetIdentityToken() pour obtenir le jeton normalisé ou le code d’erreur spécifique qui est incorporé à une exception.

        Cette fonction n’est pas appelée si l’application appelle explicitement la fonction ConsumerIdentityService::Cancel() pour annuler une session d’ouverture de session.

        Paramètres

        pParameter: Le pointeur vers une variable définie par l’application qui est passée à la fonction ConsumerIdentityService::Login().

        Codes d’erreur

        Valeur

        Signification

        ADP_CI_INVALID_IDENTITY_PROVIDER

        Les données du fournisseur d’identité fournies par Intel Identity Service ne sont pas valides ou sont incomplètes

        ADP_CI_INVALID_IDENTITY_TOKEN

        Les données du jeton d’identité normalisé fournies par Intel Identity Service ne sont pas valides ou sont incomplètes

        ADP_CI_INVALID_IDENTITY_TOKEN_SIGNATURE

        La vérification de la signature du jeton d’identité normalisé a échoué

        ADP_CI_REQUEST_TIMEOUT

        L’utilisateur final ne termine pas l’ouverture de session dans le temps imparti.

        ADP_CI_USER_ACCESS_DENY

        L’utilisateur final n’accorde pas de droits d’accès à l’application

        ADP_CI_INVALID_OPERATION

        L’application appelle les API Consumer Identity Service dans une séquence inattendue.

        ADP_FAILURE

        Une erreur générale se produit, qui n’est pas couverte par les codes d’erreur ci-dessus.

        Exemple de code d’appel Consumer Identity Service

        L’exemple suivant montre l’utilisation typique de l’appel Consumer Identity Service.

        [cpp]

        #include "adpcppf.h"

        #include

        using namespace std;

        static Intel::Adp::Application *g_pCISampleApp = NULL;

        void LoginCallBack(void*)

        {

           try {

            if (g_pCISampleApp != NULL) {

              // Obtenez l’instance du service d’identité client

              ConsumerIdentityService* pService = g_pCISampleApp->GetConsumerIdentityService();

              // Obtenez l’instance de l’objet IdentityToken.

              IdentityToken token = pService->GetIdentityToken();

              // Ici, requête des propriétés du jeton d’identité

            }

          }

           // Ici, le gestionnaire d'exceptions

        }

        int _tmain(int argc, _TCHAR* argv[])

        {

          // Authentification de l’application

           try {

            g_pCISampleApp = new Application(ADP_DEBUG_APPLICATIONID);

          }

           // Ici, le gestionnaire d'exceptions

          // Appel Consumer Identity Service

          ConsumerIdentityService* pService = NULL;

           try {

            // Obtenez l’instance du service d’identité client

            pService = g_pCISampleApp->GetConsumerIdentityService();

            // Obtenir une liste des objets IdentityProvider qui sont pris en charge par le service d’identité Intel.

            vector providers = pService->GetIdentityProviders();

            // Commencer à ouvrir une session auprès du premier fournisseur d’identité

            pService->Login(providers[0], LoginCallBack, NULL);

          }

           // Ici, le gestionnaire d'exceptions

          // Supprimer le pointeur de l’application

          if (g_pCISampleApp != NULL) {

            delete g_pCISampleApp;

            g_pCISampleApp = NULL;

          }

           return 0;

        }

        [/cpp]

        Rapport d'incident

        La bibliothèque du kit de développement logiciel Intel AppUp prend en charge la signalisation d'incidents qui fournit un cliché de l'état dans lequel se trouve l'application lorsqu'un incident se produit. Les rapports d'incidents par défaut sont automatiquement activés lors de l'exécution du constructeur d'application ; vous n'avez donc pas à activer explicitement cette fonctionnalité. Les rapports d'incident par défaut sont accessibles depuis Mon tableau de bord sur le portail de la Zone des développeurs Intel. Ce rapport contient des informations sur le contexte de l'application, l'environnement d'exécution, l'identification du SDK et un vidage de la pile du cœur. Il est possible de visualiser le rapport complet en cliquant sur le lien Détails d'un rapport.

        Le Guide du développeur du kit de développement logiciel Intel AppUp® pour C++ fournit davantage d'informations sur Mon tableau de bord et décrit comment fonctionne le signalement d'incident au niveau du système client.

        La signalisation personnalisée d'incidents vous permet de fournir d'autres informations que la signalisation par défaut. La signalisation personnalisée s'implémente grâce à la définition d'une classe MyCrashReport de rapports personnalisés, dérivée de la classe DefaultCrashReport du SDK. La définition dans le code source de MyCrashReport (ou de tout autre objet dérivé de DefaultCrashReport) désactive alors automatiquement le rapport d'incidents par défaut.

        Le tableau ci-dessous indique les champs pouvant être contenus dans un enregistrement d'incident, la colonne Source définissant la source (SDK ou développeur) des informations du champ correspondant. En tant que développeur, vous pouvez modifier les champs dont la Source est Développeur. Les champs sont modifiés en remplaçant le champ par défaut.

        Remarque :  vous êtes responsable de vous assurer que les rapports d'incident personnalisés ne contiennent pas de données qui violent la politique de confidentialité d'Intel. Voir http://software.intel.com/fr-fr/appup/ pour davantage d'informations.

         

        Champs et sources des rapports d'incident personnalisés

        Champs des rapports d'incident

        Colonne Mon tableau de bord

        Source

        Nom de l'application

        Non (mais inclus dans les détails)

        SDK

        ID de l'application

        Non (mais inclus dans les détails)

        SDK

        ModuleName

        Module (et dans les détails)

        Développeur

        LineNumber

        Ligne (et dans les détails)

        Développeur

        Catégorie

        Non (mais inclus dans les détails)

        Développeur

        Message

        Messages (et dans les détails)

        Développeur

        ErrorData

        Non (mais inclus dans les détails)

        Développeur

        Niveau d'API du SDK

        Non (mais inclus dans les détails)

        SDK

        Runtime

        Runtime (et dans les détails)

        SDK

        Version du runtime

        Non (mais inclus dans les détails)

        SDK

        SE

        SE (et dans les détails)

        SDK

        Version du système d'exploitation

        Non (mais inclus dans les détails)

        SDK

        Horodatage

        Horodatage (et dans les détails)

        SDK

        Jusqu'à 20 champs personnalisés

        (réservé pour une utilisation ultérieure)

        Développeur

          

        Les rapports personnalisés d'incidents sont définis immédiatement après l'appel Application Constructor du SDK de manière à ce qu'ils puissent inclure des données aussitôt qu'il est raisonnablement possible dans l'exécution de l'application.

        Les champs dont la souplesse de personnalisation est la plus grande sont indiqués ci-dessous :

        • Le champ Category permet de créer des catégories en vue de trier les rapports d'incident sur le portail de la Zone des développeurs Intel. Par exemple, vous pouvez créer des catégories appelées « MÉMOIRE », « ES », « ERREUR UTILISATEUR », etc.

        • Le champ Error Data vous permet de créer vos propres vidages de pile ou longs messages d'erreur vous aidant à comprendre pourquoi l'incident s'est produit.

        Remarque : Certains plantages peuvent aller jusqu'à bloquer le système du client. Dans ces cas, la durée de stockage d'un rapport d'incident sur le système du client peut être limitée. Pour optimiser l'obtention d'informations sur les plantages, vous devez peser le pour et le contre entre la quantité d'informations à inclure dans un rapport personnalisé d'incident et le créneau de temps potentiellement limité pendant lequel vous pouvez stocker des informations sur le système du client.

          

        Structure de classes de signalement d'accidents

        Les classes suivantes de rapports d'incidents sont incluses dans le framework C++ du SDK.

        AbstractCrashReport

        AbstractCrashReport est une classe abstraite comportant des méthodes virtuelles pures conçues pour remplir avec les données existant dans la classe. Le système pouvant se trouver dans un état non stable, l'allocation des données dans la pile est à éviter, dans la mesure du possible. Ces méthodes seront appelées par le framework sous-jacent pour collecter les données à soumettre dans les rapports d'incidents. En mettant en œuvre une sous-classe d'AbstractCrashReport, vous pouvez obtenir le contrôle de chacun des champs qui sera retourné pendant le processus de signalement d'incidents. En revanche, cela vous oblige à mettre en œuvre chaque champ.

        DefaultCrashReport

        La classe DefaultCrashReport est une mise en oeuvre de référence de la classe AbstractCrashReport et elle est installée par défaut. La mise en œuvre par défaut fait de son mieux pour collecter des données censées être appropriées et exactes dans la plupart des cas. Mais vous pouvez tout à fait sous-classer DefaultCrashReport pour personnaliser un ou plusieurs champs.

        AdvancedCrashReport (Microsoft Windows* uniquement)

        La classe AdvancedCrashReport fournit une mise en œuvre sophistiquée de la classe AbstractCrashReport. Cette mise en œuvre exploite une classe Advanced CallStack qui hérite de CallStack et qui fournit une présentation complète du callstack (module, symbole, numéro de ligne). Pour fournir ces fonctionnalités enrichies, la classe AdvancedCrashReport utilise la bibliothèque DbgHelp d'utilitaires, distribuée avec le package Microsoft Debugging Tools for Windows*.

        Détails d'AbstractCrashReport

        AbstractCrashReport est la classe de base dont dérivent tous les rapports d'incidents. Vous pouvez hériter d'AbstractCrashReport dès lors que vous mettez en œuvre chacune des méthodes de la classe. (vous pouvez vous contenter d'étendre la classe DefaultCrashReport si vous voulez juste substituer certaines de ces méthodes.) La classe C ADP_ReportCrash est développée par rapport à la signature suivante :

        [cpp]

            ADP_RET_CODE ADP_ReportCrash(

                const wchar_t            *Module,

               unsigned long                       LineNumber,

                const wchar_t            *Message,

                const wchar_t            *Category,

                const wchar_t            *ErrorData,

               unsigned long                       ErrorDataSize,

                ADP_CrashReportField     *CustomFields,

                unsigned long            CustomFieldNumber

            };

        [/cpp]

        Les arguments ci-après ont été déclarés dans AbstractCrashReport sous les noms suivants en tant que variables membres :

        [cpp]

            wchar_t module[80];

            wchar_t message[80];

            wchar_t category[80];

            wchar_t errorData[4000];

            long    lineNumber;

            ADP_CrashReportField* pCrashReportFields;

            long    crashReportFieldCount;

        [/cpp]

        Si vous souhaitez fournir un rapport d'incidents personnalisé sans gestionnaires, vous devrez substituer aux méthodes abstraites pures d'AbstractCrashReport en remplissant ces variables (ces variables, en retour, sont utilisées dans l'appel à la classe C ADP_ReportCrash).

        La classe AbstractCrashReport offre les overrides virtuels suivants :

             virtual void PopulateModuleName()

             Cette méthode est fournie pour remplir la variable membre AbstractCrashReport::module.

             virtual void PopulateLineNumber()

             Cette méthode est fournie pour remplir la variable membre AbstractCrashReport::lineNumber.

             virtual void PopulateMessage()

             Cette méthode est fournie pour remplir la variable membre AbstractCrashReport::message

             virtual void PopulateCategory()

             Cette méthode est fournie pour remplir la variable membre AbstractCrashReport::category.

             virtual void PopulateErrorData()

             Cette méthode est fournie pour remplir la variable membre AbstractCrashReport::errorData.

             virtual void PopulateCrashReportFields()

             Cette méthode est fournie pour remplir les variables membres AbstractCrashReport:: pCrashReportFields
        et AbstractCrashReport::crashReportFieldCount.

        Les arguments ci-après ont été déclarés dans AbstractCrashReport sous les noms suivants en tant que variables membres :

        [cpp]

            protected StringBuffer errorData = new StringBuffer();

            protected String errorMessage = "";

            protected String errorModule = "";

            protected long errorLine = 0;

            protected String errorCategory = "";

            protected AdpCrashReportField[] crashReportFields = null;

        [/cpp]

        Détails de DefaultCrashReport

        La classe DefaultCrashReport fournit une mise en œuvre de référence de la classe AbstractCrashReport. Cette mise en œuvre exploite une classe CallStack qui vous est fournie sous la forme d'un fichier hpp. Dans cette configuration, toute la logique métier est exposée sous forme de fichier header et toutes les méthodes de la classe sont déclarées inline. CallStack tente de traverser le callstack du thread d'appels, en compilant dans des structures CallStackEntry les informations de chaque cadre de la pile et en stockant chacune de ces structures dans un conteneur de liste STL. Vous trouverez dans le Guide du développeur C++ pour le kit de développement logiciel Intel Intel AppUp® un exemple de rapport personnalisé basé sur DefaultCrashReport. Une CallStackEntry présente la structure suivante :

        [cpp]

            struct CallStackEntry {

                   wstring fileName;

                   wstring moduleName;

                   wstring symbolName;

                   unsigned long lineNumber;

                   void* pAddress;

         

                   CallStackEntry();

                   wstring str();

           };

        [/cpp]

        Détails de CallStack

        CallStack utilise la structure CONTEXT de l'API Win32, jointe à l'arithmétique des pointeurs, pour traverser la pile et remplir CallStackEntryList avec un ensemble représentant les cadres de la pile d'un thread donné.

        CallStack comporte un constructeur par défaut, qui ne prend aucun argument, et qui initialise les variables internes de l'objet. Si la classe CallStack doit enregistrer l'état de la pile d'un thread appelant, le développeur invoquera la méthode CallStack::Parse. Dans les environnements Win32, la méthode CallStack::Parse prend une structure CONTEXT. Pour extraire arbitrairement cet enregistrement, vous pouvez invoquer la méthode ::RtlCaptureContext de la bibliothèque Win32.
         

        [cpp]

            // Exécution de CallStack::Parse pour Win32 à une exécution arbitraire

            // point.

            CallStack callStack;

            CONTEXT context;

            ::RtlCaptureContext(&context);

         

            CallStackEntryList entries = callStack.Parse(&context);

        [/cpp]

        CallStackEntryList&  Parse()

        Analyse la pile d'appels du thread, en enregistrant les informations dans une liste de collecte STL CallStackEntry.

        Paramètres

             Aucun

        Exceptions

             Aucun

        Valeurs retournées

        Valeur

        Description

        CallStackEntryList&

        Référence à la CallStackEntryList maintenue par l'objet CallStack.

        CallStackEntryList&  GetEntries()

        Retourne une référence à la CallStackEntryList maintenue par l’objet CallStack.

        Paramètres

             Aucun

        Exceptions

             Aucun

        Valeurs retournées

        Valeur

        Description

        CallStackEntryList&

        Référence à la CallStackEntryList maintenue par l'objet CallStack.

        Détails d'AdvancedCrashReport

        La classe AdvancedCrashReport fournit une mise en œuvre sophistiquée de la classe AbstractCrashReport. Cette implémentation exploite une classe AdvancedCallStack qui hérite de CallStack et qui fournit une présentation complète du callstack (module, symbole, numéro de ligne). Pour fournir ces fonctionnalités enrichies, la classe AdvancedCrashReport utilise la bibliothèque DbgHelp d'utilitaires, distribuée avec le package Microsoft Debugging Tools for Windows* OS.

        La procédure complète pour activer AdvancedCrashReport est la suivante :

        • Téléchargez et installez la dernière version du package Microsoft Debugging Tools for Windows*.

        • Définissez le symbole de préprocesseur _ADP_ADVANCED_CRASHREPORT dans le fichier de projet de l'application.

        • Incluez le fichier header AdvancedCrashReport.h avec votre application.

        • Ajoutez la bibliothèque dbghelp.lib à la liste des bibliothèques auxquelles est liée l'application.

        Le système DbgHelp.dll est disponible sur la plupart des installations de SE de Microsoft Windows*, mais, sur les anciens systèmes, sa version risque de ne pas être compatible avec la version de DbgHelp.lib qui a été liée à l'application. Pour être sûrs que c'est la bonne version de DbgHelp.dll qui sera disponible au moment de l'exécution sur le système de l'utilisateur final, les développeurs peuvent envisager de redistribuer DbgHelp.dll avec leurs applications. Reportez-vous à la documentation sur la licence de DbgHelp pour connaître les termes et les conditions de sa redistribution.

        L'exemple de code suivant montre comment installer le gestionnaire AdvancedCrashReport pour l'application.

        [cpp]

        #include "AdvancedCrashReport.h"

        &ldots;

        Application::SetCrashReport(new AdvancedCrashReport);

        ...  

        [/cpp]

        Exceptions

        La bibliothèque du SDK comprend des classes d'exceptions prédéfinies, trois pour les erreurs et une pour les avertissements, qui permettent une plus grande granularité dans la gestion des exceptions. Ces classes d'exceptions sont les suivantes :

        Classes d'exceptions d'erreurs
        • InitializationException – intercepte les exceptions d'erreurs levées lorsque le constructeur d'application de la bibliothèque du SDK tente d'initialiser le code de la bibliothèque du SDK. Cette classe est dérivée de la classe AdpErrorException.

        • UnauthorizedException – intercepte les exceptions d'erreurs levées lorsque le code de la bibliothèque du SDK tente d'autoriser l'application. Cette classe est dérivée de la classe AdpErrorException.

        • AdpRuntimeException – intercepte les exceptions d'erreurs générales du runtime lors de l'exécution du code de la bibliothèque du SDK. Cette classe est dérivée de la classe AdpErrorException.

        Classe d'exception d'avertissement
        • AdpWarningException – intercepte les exceptions d'avertissement lors de l'exécution du code de la bibliothèque du SDK.

        Il est à noter qu'AdpErrorException est la classe de base des trois classes d'exceptions d'erreurs (voir schéma ci-dessous). AdpErrorException et AdpWarningException dérivent toutes les deux de la même classe de base, AdpException.

        Les sous-sections qui suivent décrivent en détail ces classes d'exceptions.

        InitializationException

        Représente une erreur survenue pendant l'initialisation de l'application. Le code de l'erreur aide à préciser la cause de l'exception d'erreur d'initialisation. Une fois l'initialisation terminée, cette exception ne pourra plus se produire.

        UnauthorizedException

        Représente un échec dans l'autorisation d'une application. Le code de l'erreur aide à préciser la cause de l'exception d'erreur d'autorisation. Une fois l'autorisation terminée, cette exception ne pourra plus se produire

        AdpRuntimeException

        Représente une erreur de la bibliothèque fondamentale sous-jacente. Le code de l'erreur aide à préciser la cause de l'exception d'erreur de runtime. Cette exception peut se produire à n'importe quel moment après l'autorisation.

        AdpWarningException

        Il s'agit de la classe d'exceptions pour des situations importantes, mais qui ne sont pas considérées comme des erreurs. Exemple : un appel EndEvent est rencontré alors qu'il n'existe aucun appel BeginEvent préalable. Le code de l'erreur aide à préciser la cause de l'exception d'erreur d'avertissement.

        Exemples de code d'exceptions

        L'exemple suivant montre la séquence d'interception en C++ venant après un appel Application Constructor. Cette séquence comprend des interceptions pour l'erreur et les classes d'exceptions. Vous trouverez plus haut, dans la section consacrée à l'appel EndEvent, un exemple d'interception de la classe d'exceptions d'avertissement.

        [cpp]

        const ApplicationId myApplicationID(0x12341234, 0x56785678, 0x12341234, 0x56785678);

         

        int main(int argc, char** argv)

            {

            Application * myApplication = NULL;

            try

            {

                myApplication = new Application(myApplicationID);

            }

            catch (InitializationException& e) {

                    // Le code de gestion des exceptions d'initialisation

                    wcout << L"Exception Initialisation interceptée dans l'application: " << e << endl;

            }

            catch (UnauthorizedException& e) {

                   // Le code de gestion des exceptions d'autorisation

                    wcout << L"Exception Unauthorized interceptée dans l'application: " << e << endl;

            }

            catch (AdpRuntimeException& e) {

                   // Le code de gestion des exceptions de runtime

                   wcout << L"Exception Runtime interceptée dans l'application: " << e << endl;

            }

        }

        [/cpp]

        Valeurs retournées/Codes d'erreur

        Le tableau suivant est une liste exhaustive des valeurs et des codes d'erreur retournés à la routine appelante par les appels à l'API du SDK, avec, pour chacun des codes, une description des conditions possibles ayant provoqué le retour. Les codes de résultat ne sont pas tous retournés pour chaque appel d'API. Reportez-vous aux informations d'un appel d'API spécifique pour connaître les codes qui peuvent être retournés pour l'appel en question. (Les informations sur un appel d'API spécifique peuvent également contenir des détails supplémentaires sur des conditions spécifiques pouvant provoquer le retour d'un code pour cet appel.)

        Les codes de résultats peuvent être obtenus de n'importe quelle classe d'exceptions en utilisant la fonction code() dans la déclaration de message.

         

        Appel API : valeurs retournées/codes d'erreur

        Valeur

        Signification

        ADP_SUCCESS

        L'opération a réussi.

        ADP_FAILURE

        L'opération a échoué.

        ADP_NOT_AVAILABLE

        L'opération a échoué car la bibliothèque du SDK n'était pas disponible. Cela peut se produire si le logiciel du centre Intel AppUp n'est pas installé correctement.

        ADP_NOT_INITIALIZED

        L'opération a échoué car la bibliothèque du SDK n'est pas initialisée. Tout appel d'API effectué avant l'initialisation retourne ce code.

        ADP_INCOMPATIBLE_VERSION

        L'opération a échoué car la version d'API de l'application n'est pas prise en charge par le logiciel actuel du centre Intel AppUp.

        ADP_AUTHORIZED

        L'exécution de l'application est autorisée.

        ADP_NOT_AUTHORIZED

        L'exécution de l'application n'est pas autorisée. Les applications peuvent choisir comment répondre, comme empêcher l'exécution d'une application, autoriser l'exécution de l'application pendant une période donnée pour permettre à l'utilisateur d'obtenir une licence, autoriser l'exécution de l'application avec des fonctionnalités limitées, etc.

        ADP_AUTHORIZATION_EXPIRED

        La licence de l'application a expiré. Les applications peuvent choisir comment répondre, comme empêcher l'exécution d'une application, autoriser l'exécution de l'application pendant une période donnée pour permettre à l'utilisateur d'obtenir une licence, autoriser l'exécution de l'application avec des fonctionnalités limitées, etc.

        ADP_NO_APP_BEGIN_EVENT

        L'opération a échoué car un appel d'événement de fin a été lancé sans appel d'événement de début préalable. Un appel Begin Event doit précéder un appel End Event dans l'application.

        ADP_TIMEOUT

        L'opération a échoué car la connexion entre la bibliothèque du SDK et le logiciel client du centre Intel AppUp a expiré.

         

        Messages d'erreur pour l'utilisateur final

        Le SDK contient des chaînes de messages d'erreur qui peuvent être extraites par les applications et affichées aux utilisateurs finaux. Ces messages sont accessibles via leur ID de message exclusif. Ils n'ont aucun mappage direct avec les codes de retour.

        Messages d'erreur pour l'utilisateur final

        ID de message

        Texte du message

        String_ADP_AUTHORIZATION_EXPIRED

        La licence de cette application a expiré.

        String_ADP_BEGINEVENT_ERROMSG

        L'application a rencontré une erreur en démarrant un enregistrement d'utilisation.

        String_ADP_ENDEVENT_ERRORMSG

        L'application a rencontré une erreur en mettant fin à un enregistrement d'utilisation.

        String_ADP_FAILURE

        L'application a rencontré une erreur critique.

        String_ADP_INCOMPATIBLE_VERSION

        Le logiciel actuel du centre Intel AppUp ne prend pas en charge cette version de l'application.

        String_ADP_NO_APP_BEGIN_EVENT

        L'application n'a pas démarré d'enregistrement d'utilisation.

        String_ADP_NOT_AUTHORIZED

        L'application n'est pas autorisée à s'exécuter sous ce compte sur cet appareil.

        String_ADP_NOT_AVAILABLE

        L'application ne parvient pas à se connecter au centre Intel AppUp.

        String_ADP_NOT_INITIALIZED

        L'application ne s'est pas initialisée correctement.

        String_ADP_TIMEOUT

        Le centre Intel AppUp n'a pas répondu dans les délais impartis.

        String_ADP_UPGRADE_ERRORMSG

        L'application n'a pas réussi à envoyer la demande de mise à niveau au centre Intel AppUp.

         

        Informations de référence sur les composants

        Cette section donne des informations de référence concernant les composants. Des exemples de code sont fournis, le cas échéant.

        Remarque : une application utilise un composant sous licence s'il existe un accord préalable entre le développeur du composant et le développeur de l'application. Il vous incombe, à vous, le développeur du composant, de veiller à l'application de la licence, à savoir de vous assurer que l'application appelante possède la licence lui permettant d'utiliser votre composant.

        Règles à observer pour le développement de composants

        Les règles qui suivent portent sur les aspects spécifiques du développement de composants :

        • Les composants sont pris en charge dans la bibliothèque du SDK par leur propre classe, la classe Component. Cette classe Component se base sur la classe Product. Le SDK prend en charge soit l'extension de la classe Component (héritage), soit l'utilisation du composant comme délégué pour appeler le framework C++. La manière recommandée de créer des composants est d'étendre la classe Component (héritage).

        • Vous devez créer la classe Application avant de créer la classe Component utilisée dans l'application.

        • Il peut exister plusieurs instances d'une classe Component dans une classe Application. De ce fait, l'autorisation des composants est gérée différemment de celle des applications :

          • Seule la première instance d'un composant effectue l'autorisation du composant. Si une exception UnauthorizedException se produit, il est possible de déterminer la raison de l'exception en interceptant cette dernière et en lisant le code de l'erreur.

          • Les instances ultérieures du composant déterminent si elles peuvent ou non s'exécuter. Pour ce faire, elles lisent une variable locale créée par le développeur, qui stocke le statut de l'autorisation initiale. Elles peuvent également appeler GetAuthorizationStatus. Ces méthodes sont plus rapides que d'obliger les instances ultérieures à chaque fois redemander leur propre autorisation.

        • Chaque instance Component doit être supprimée de manière indépendante.

        • Les ID de composant sont différents des ID d’application.

        • La gestion des exceptions de composants est la même que celle pour les applications, à l'exception des différences décrites ci-dessus pour les autorisations.

        • L'instrumentation (événements Begin Event et End Event) n'est pas prise en charge au niveau composant.

        • Le rapport d'incidents n'est pas prise en charge au niveau composant.

        ID de composants

        L'ID de composant est un identifiant unique pour les composants du centre Intel AppUp. Il existe deux types d'ID de composant :  (1) les ID de débogage et (2) les ID de production. Les ID de débogage sont utilisés pour les tests de composants. Une fois ceux-ci effectués, vous devez remplacer l'ID de débogage de composant par un ID de production de composant afin de pouvoir télécharger votre application vers le portail de la Zone des développeurs Intel.

        • ID de débogage de l'application – pendant le développement, l'ID de débogage permet les tests avec le débogueur de logiciel Intel AppUp. L'ID de débogage est un numéro de 128 bits, exprimé sous forme de chaîne utilisant des constantes prédéfinies. Il existe deux versions de l'ID de débogage :

          • ADP_DEBUG_COMPONENTID   utilisé avec le débogueur de logiciel Intel AppUp pour obtenir une réponse ADP_AUTHORIZED. Cela permet de tester et de déboguer la plus grande partie de l'application. La valeur effective de cet ID de débogage est contenue dans la bibliothèque du SDK.

          • ADP_EXPIRED_COMPONENTID   utilisé avec le débogueur de logiciel Intel AppUp pour obtenir une réponse ADP_AUTHORIZATION_EXPIRED. Cela permet de tester et de déboguer la branche « expirée » de l'application. La valeur effective de cet ID de débogage est contenue dans la bibliothèque du SDK.

        • ID de production de composant – Les ID de production s'obtiennent auprès du portail de la Zone des développeurs Intel, ce qui nécessite que vous vous inscriviez en tant que développeur Intel AppUp. L'ID de production est un nombre de 128 bits composé de quatre nombres entiers au format hexadécimal.

        Appel GetAuthorizationStatus pour les composants

        L’appel GetAuthorizationStatus permet de prendre en charge les applications pour les anciennes versions bêta du SDK. Cet appel permet à une application de déterminer si un composant est autorisé à s'exécuter après l'autorisation initiale donnée au composant. La valeur retournée indique le statut d'origine de l'autorisation du constructeur du composant à n'importe quel moment une fois que l'appel Component Constructor a été effectué. (lire la section Remarques avant de recourir à cet appel).

        Syntaxe

        [cpp]

            static RETURN GetAuthorizationStatus();

        [/cpp]

        Paramètres

        Aucun.

          

        Codes d'erreur (type de données ADP_RET_CODE)

        Valeur

        Signification

        ADP_AUTHORIZED

        Le composant est autorisé à s'exécuter.

        ADP_NOT_AUTHORIZED

        Le composant n'est pas autorisé à s'exécuter. Les composants peuvent choisir la manière de répondre : empêcher un composant de s'exécuter ; autoriser le composant à s'exécuter pendant une période de grâce pour permettre à l'utilisateur d'obtenir une licence ; autoriser le composant à s'exécuter avec des fonctionnalités limitées ; etc.

        ADP_AUTHORIZATION_EXPIRED

        La licence du composant a expiré. Les composants peuvent choisir la manière de répondre : empêcher un composant de s'exécuter ; autoriser le composant à s'exécuter pendant une période de grâce pour permettre à l'utilisateur d'obtenir une licence ; autoriser le composant à s'exécuter avec des fonctionnalités limitées ; etc.

        ADP_TIMEOUT

        L'opération a échoué car la connexion entre la bibliothèque du SDK et le logiciel client du centre Intel AppUp a expiré.

         

        Notes

        • La méthode recommandée pour déterminer le statut d'une autorisation après que l'autorisation initiale a été donnée consiste à utiliser une variable locale créée par le développeur. L’appel GetAuthorizationStatus n'est fourni que pour permettre la prise en charge des anciennes versions bêta du SDK. Le recours à cet appel doit être évité pour les applications utilisant les versions 1.0 et plus récentes du SDK C++.

        • Nous vous recommandons de tenter une nouvelle procédure d'autorisation si vous recevez une erreur ADP_TIMEOUT à la première tentative.

        Exemple de code de composant

        L'exemple suivant montre le code d'un composant qui extrait et affiche les informations relatives à la plate-forme. Le composant est un dérivé de la classe Component et il utilise un ID de débogage pendant le développement et les tests (un ID de production devra être inséré à la place de l'ID de débogage avant la soumission du composant sur le portail de la Zone des développeurs Intel).

        [cpp]

        ##include "stdafx.h"

         

        // Utilisez DEBUG_ID lors du développement du composant, mais pensez à remplacer ce qui suit

        ADP_TIMEOUT

         

        SampleComponent::SampleComponent(void): Component(ADP_DEBUG_COMPONENTID)

        {

         

        }

         

         

        SampleComponent::~SampleComponent(void)

        {

         

        }

         

         

        // Ce composant extrait les informations relatives à la plate-forme et les imprime

         

        void SampleComponent::GetPlatformInfo(CWnd* pWnd)

        {

            SYSTEM_INFO siSysInfo;

            GetSystemInfo(&siSysInfo);

            CString strPlatformInfo;

            CString strProcessArchitecture;

            switch(siSysInfo.wProcessorArchitecture)

            {

            case 0:

                strProcessArchitecture = _T("x86");

                break;

            case 6:

                strProcessArchitecture = _T("Famille des processeurs Intel Itanium");

                break;

           case 9:

                strProcessArchitecture = _T("x64");

                break;

           case 0xffff:

           default:

                strProcessArchitecture = _T("Architecture inconnue");

                break;

            }

            strPlatformInfo.FormatMessage( _T("Composant autorisé à s'exécuter.\n\n

                Matériels\n\nTaille de page : %1!u!\n

                Nombre de processeurs : %2!u!\n

                Architecture des processeurs : %3!s!\n"),

                siSysInfo.dwPageSize,

                siSysInfo.dwNumberOfProcessors,

                strProcessArchitecture);

            pWnd->SetWindowTextW(strPlatformInfo);

        }

        [/cpp]

        Informations légales

        LES INFORMATIONS CONTENUES DANS CE DOCUMENT CONCERNENT LES PRODUITS INTEL(R). LA SOCIÉTÉ INTEL N'ACCORDE AUCUNE LICENCE EXPRESSE, NI IMPLICITE, PAR FORCLUSION OU AUTRE SUR UN DROIT QUELCONQUE DE PROPRIÉTÉ INTELLECTUELLE. À L’EXCEPTION DES DISPOSITIONS PRÉVUES AUX CONDITIONS GÉNÉRALES DE VENTE D’INTEL POUR LESDITS PRODUITS, INTEL DÉCLINE TOUTE RESPONSABILITÉ ET EXCLUT TOUTE GARANTIE EXPLICITE OU IMPLICITE SE RAPPORTANT À LEUR VENTE OU À LEUR UTILISATION. INTEL DÉCLINE NOTAMMENT TOUTE RESPONSABILITÉ ET TOUTE GARANTIE CONCERNANT LEUR ADÉQUATION À UN USAGE PARTICULIER, LEUR QUALITÉ LOYALE ET MARCHANDE, LA CONTREFAÇON DE TOUT BREVET, LA VIOLATION DE DROITS D’AUTEUR OU D’AUTRES DROITS DE PROPRIÉTÉ INTELLECTUELLE.
        SAUF ACCORD ÉCRIT D’INTEL DANS CE SENS, SES PRODUITS NE SONT PAS À UTILISER DANS UN CONTEXTE OÙ LEUR DÉFAILLANCE POURRAIT CONDUIRE À DES SITUATIONS DE PRÉJUDICES CORPORELS OU À LA MORT.
        Intel se réserve le droit de modifier à tout moment sans préavis les spécifications et les descriptions de ses produits. Les concepteurs ne doivent pas se fier à l'absence ou aux caractéristiques de fonctionnalités ou d'instructions marquées comme « réservées » ou « non définies ». Intel se réserve la possibilité de compléter ses définitions à l'avenir et ne saurait être tenue responsable de quelque manière que ce soit pour les conflits et les incompatibilités découlant des modifications qui y seront apportées alors. Les informations fournies ici sont sujettes à modification sans préavis, ne finalisez aucune création avec cette information.
        Les produits décrits dans le présent document peuvent comporter des défauts ou erreurs de conception, connus sous le nom d’errata, susceptibles de faire s’écarter le produit des spécifications publiées. La liste des errata déjà identifiés peut être fournie sur demande.
        Interrogez votre point de vente local ou votre distributeur Intel pour obtenir les plus récentes spécifications avant de passer commande d'un produit.
        Des copies des documents comportant un numéro d'ordre et référencés dans ce document, ou d'autre documents Intel, peuvent être obtenues en appelant le 1-800-548-4725 ou en se rendant sur le site Web d'Intel.

        La numérotation des processeurs Intel ne constitue pas une mesure de performances. Cela permet de différencier des modèles appartenant à une même famille de processeurs, et non à des familles différentes. Pour de plus amples informations, consultez http://www.intel.com/content/www/fr/fr/processors/processor-numbers.

        Pour les versions bêta et de pré-lancement des produits. Ce document contient des informations concernant des produits en phase de développement.

        BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Atom, Centrino Atom Inside, Centrino Inside, le logo Centrino, Core Inside, FlashFile, i960, InstantIP, Intel, le logo Intel, Intel386, Intel486, IntelDX2, IntelDX4, IntelSX2, Intel Atom, Intel Atom Inside, Intel Core, Intel Inside, le logo Intel Inside, Intel. Leap ahead., Intel, Leap ahead., Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel StrataFlash, Intel Viiv, Intel vPro, Intel XScale, Itanium, Itanium Inside, MCS, MMX, Oplus, OverDrive, PDCharm, Pentium, Pentium Inside, skoool, Sound Mark, The Journey Inside, Viiv Inside, vPro Inside, VTune, Xeon et Xeon Inside sont des marques de commerce d'Intel Corporation aux États-Unis et dans d'autres pays.

        * Les autres noms et désignations peuvent être revendiqués comme marques par des tiers.

        Copyright (C) 2011, Intel Corporation. Tous droits réservés.

        Les captures d'écran de produits Microsoft sont reproduites avec l'autorisation de Microsoft Corporation.

        Reportez-vous à notre Notice d'optimisation pour plus d'informations sur les choix et l'optimisation des performances dans les produits logiciels Intel.