Intel AppUp® Software Development Kit API Reference for C++

SDK Version 2.0  Copyright © 2011 Intel Corporation.  All Rights Reserved.  Document Number: 324249-006US.

Contents


About this Document

Intended Audience

Using this API Reference

Conventions and Symbols

Related Information

Revision History

Application Reference Information

Configuration and Build Information

Class Structure

Application Constructor Call

Authorization Code Examples

GetAuthorizationStatus Call

GetAuthorizationStatus Call Code Example

Cleanup Code

Instrumentation

Begin Event Call

End Event Call

In-App Purchase APIs

In-App Upgrade

In-App Unlocking Call

Consumer Identity Service Call

Crash Reporting

Crash Reporting Class Structure

AbstractCrashReport Details

DefaultCrashReport Details

CallStack Details

AdvancedCrashReport Details

Exceptions

InitializationException

UnauthorizedException

AdpRuntimeException

AdpWarningException

Code Example for Exceptions

Return/Error Codes

End User Error Messages

Component Reference Information

Component Guidelines

GetAuthorizationStatus Call for Components

Component Code Example

Legal Information

About this Document

This document is for developers using the Intel AppUp® Software Development Kit 2.0 for C/C++ to develop C++ applications and components in a Microsoft Windows* development environment and targeted for a Microsoft Windows* runtime environment. The SDK (Software Development Kit) includes programming libraries, documentation, and sample code to help developers create, test, and submit C++ applications and components intended for distribution via the Intel AppUp® center.

Note: This document covers C++ support only, even though the SDK also supports C. Information on C support is provided in separate documentation.

Intended Audience

This document is intended for experienced software developers who are developing applications and components for the Intel AppUp center. These can be new applications/components or existing ones being ported for the Intel AppUp center. This SDK supports development of C++ applications/components in a Microsoft Windows* 7 or Windows* XP development environment and targeted for a Microsoft Windows* 7 or Windows* XP runtime environment.

Information about the specific editions and versions of the environments that are supported is provided in the Release Notes for the SDK.

Using this API Reference

This API reference contains the following sections:

  • About this Document, introduces the contents and conventions of this document.

  • Application Reference Information, documents the SDK API Calls for applications. Code examples are provided, as appropriate.

  • Component Reference Information, documents the SDK API Calls for components. Code examples are provided, as appropriate.

Conventions and Symbols

The following table shows the conventions used in this document.

This type style

Indicates an element of syntax, reserved word, keyword, filename, computer output, or part of a program example. The text appears in lowercase unless uppercase is significant.

This type style

Indicates the exact characters you type as input. Also used to highlight the elements of a graphical user interface such as buttons and menu names or filenames and labels when discussing program examples.

This type style

Indicates a placeholder for an identifier, an expression, a string, a symbol, or a value. Substitute actual item(s) for the placeholder.

Hyperlink

Indicates a hyperlink to internal or external information. Use Ctrl+mouse click to navigate.

Note: 

Indicates an important comment or side topic.

Related Information

Getting Started information for the C++ SDK is provided in the Intel AppUp® Software Development Kit Developer Guide for C++ document, which is shipped with the Intel AppUp® Software Development Kit for C/C++. The SDK is available on the Intel® Developer Zone portal.

Revision History

Document Number

Revision Number

Description

Revision Date

324249

001

Initial document release to support C/C++ SDK V1.0

August 2010

 

002

Updated exception information

September 2010

 

003

Updated to support C/C++ SDK V1.1:

• Added End User Error Message Information.

• Revised some code samples.

November 2010

 

004

Updated to support C/C++ SDK V1.1.1:

• Added In-App Upgrade API information.

• Clarifications to existing content.

February 2011

 

005

Updated to support C/C++ SDK V1.1.2:

• Updated to comprehend Intel AppUp® Software Debugger 1.1.2

April 2011

 

006

Updated to support C/C++ SDK V2.0:

• Added In-App Unlocking API information

• Added Consumer Identity API information

November 2011

 

Application Reference Information

This section documents the SDK API Calls for Applications. The following subsections are provided:

  • Configuration and Build Information - Documents general configuration and build information needed to create applications.

  • Class Structure - Defines the class structure for the SDK library.

  • Application Constructor Call - Documents the SDK library Application Constructor call, which is required to authorize Intel AppUp center applications to run on the client system.

  • Instrumentation Calls - Documents the SDK library calls to implement Instrumentation (metering) of applications.

  • In-App Purchase APIs - Documents the SDK library In-App Purchase APIs that allow application upgrades and purchases of new application features.

  • Consumer Identity Call - Documents the API call to log into an application with a third party identity provider such as Facebook*, or Google* and obtain a ’normalized’ identity token, in the standard format defined by Intel.

  • Custom Crash Reporting - Documents the method to implement custom Crash Reporting, when default Crash Reporting is not desired.

  • Exceptions - Documents the SDK Exception Classes that are supported.

  • Return/Error Codes - Documents the Return/Error codes that are supported.

  • End User Error Messages - Documents the error messages that can be displayed to end users.

Code examples are provided, as appropriate. Information on components is covered in Component Reference Information.

Configuration and Build Information

The following list provides basic configuration and build information needed to create applications:

          • Verify that Visual Studio has statically linked the application to the Application Service library for the target runtimes. These libraries are as follows:

        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

        • The default pathname to the libraries is: Program Files/Intel/IntelAppUpSDK/Cpp/lib/.

         

        Class Structure

        The Application class is the root of the C++ Framework’s class hierarchy for applications. The Component class is the root of the C++ Framework’s class hierarchy for components. Refer to the Component Reference Information subsection later in this section for detailed information on components. As shown below, both of these classes are based on a common Product class. The SDK supports extending the Application class (inheritance) and using the application as a delegate to call the C++ framework. Extending the Application class is the recommended approach for new applications. Only one instance of the Application class can be created.

         

         

        Application Constructor Call

        The Application Constructor call is the only required call for Intel AppUp center C++ applications. When invoked, the application constructor performs the following operations:  (1) it initializes the SDK library, and (2) it authorizes the application via the Intel AppUp center. Exceptions are thrown if these operations fail. In addition, default Crash Reporting is enabled, unless custom Crash Reporting is implemented.

        The Application Constructor call must be placed in the initialization code for the application. Header code and Cleanup code must also be included in the application to support this call. The Application Constructor call should be followed by an exception handler.

        Syntax

        const ApplicationId myApplicationID(ApplicationID);
         
        int main(int argc, char** argv) {
            Application * myApplication = NULL;
            try {
                myApplication = new Application(myApplicationID);
            }
                // catches for exception handling
        }
        

        Parameters

        myApplication:  name of the object (the application)

        ApplicationID:  Application GUID in string or integer format. The data type of the GUID is four unsigned, long integers, as follows:
         

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

        See the Application ID discussion later.

        If the Application Constructor is successful, then an Application object is returned. Otherwise an exception is thrown. The following exceptions are supported:

        • InitializationException - Failure while attempting to initialize the SDK library code.

        • UnauthorizedException - Failure while attempting to authorize the application.

        • AdpRuntimeException - Failure in the general runtime environment.

        Error Codes (ADP_RET_CODE data type)

        Value

        Meaning

        ADP_FAILURE

        Operation was unsuccessful. It can also indicate that more than one instantiation of the application was attempted.

        ADP_NOT_AVAILABLE

        Operation failed because the SDK library was not available. This can occur if the Intel AppUp center software is not installed properly.

        ADP_NOT_INITIALIZED

        Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.

        ADP_INCOMPATIBLE_VERSION

        Operation failed because the API version of the application is not supported by the current Intel AppUp center software.

        ADP_NOT_AUTHORIZED

        The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

        ADP_AUTHORIZATION_EXPIRED

        The application’s license has expired. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

        ADP_TIMEOUT

        Operation failed because the connection between the SDK and the Intel AppUp center client software timed out.

          

        Application IDs

        The Application ID is a unique identifier for Intel AppUp center applications. There are two types of application GUIDs:  (1) a Debug Application ID, and (2) a Production Application ID. Debug Application IDs are used for testing applications. You must replace the Debug Application ID with a Production Application ID after testing in order to upload your application to the Intel Developer Zone portal.

        Debug Application ID - During development, the Application Debug ID allows testing with the Intel AppUp Software Debugger. This Debug ID is a 128-bit number, expressed as a string using predefined constants. Two versions of a Debug ID exist:

        • ADP_DEBUG_APPLICATIONID:  Used with the Intel AppUp Software Debugger to get an ADP_AUTHORIZED response back. This allows most of the application to be tested and debugged. The value of this Debug ID is all one's.

        • ADP_EXPIRED_APPLICATIONID:  Used with the Intel AppUp Software Debugger to get an ADP_AUTHORIZATION_EXPIRED response back. This allows the "expired” branch of the application to be tested and debugged. The value of this Debug ID is all zero's.

        Production Application ID - Production IDs are obtained from the Intel Developer Zone portal, which requires that you enroll as an Intel AppUp® developer. The Production ID is a 128-bit number organized as four integers in hex format.

        Notes

        • The following header must be included prior to invoking the Application Constructor call: 

         

        /// <ADP>
        #include <adpcppf.h>
        /// </ADP>
        

        • A sensible approach to handling an ADP_TIMEOUT error during the first authorization attempt is to attempt authorization again.

        • The recommended method to check the original authorization status of an application at any point after the Application Constructor call has completed is via a developer-created, local variable.

        Authorization Code Examples

        Using Debug Application ID From SDK Library

        The following example uses a Debug Application ID and includes a basic exception handler. The header code has been previously inserted.

         

        /// <ADP>
        const ApplicationId myApplicationID(AdpConstants.ADP_DEBUG_APPLICATIONID);
            /// Note: replace AdpConstants.ADP_DEBUG_APPLICATIONID with the actual application ID
            /// once you obtain it from Intel Developer Zone web portal
            /// To test Expired ID, use AdpConstants.ADP_EXPIRED_APPLICATIONID
        int main(int argc, char** argv) {
            Application * myApplication = NULL;
            try {
                myApplication = new Application(myApplicationID);
            } catch (AdpException& e) {
                cout << "Caught exception in application: " <<
                         e.what() << endl;
            }
        }
        /// </ADP>
        

        Using Production Application ID

        The following example uses a Production Application ID and a basic exception handler. The header code has been previously inserted.

        /// <ADP>
        const ApplicationId myApplicationID(0x12341234, 0x56785678, 0x12341234, 0x56785678);
        int main(int argc, char** argv) {
            Application * myApplication = NULL;
            try {
                myApplication = new Application(myApplicationID);
            }
            /// Exception handler goes here
        }
        /// </ADP>
        

        GetAuthorizationStatus Call

        The GetAuthorizationStatus call provides legacy support for Beta versions of the SDK. This call shows the original authorization status of the application constructor at any point after the application constructor call has completed. (Read the Notes section prior to using this call.)

        Syntax

            static RETURN GetAuthorizationStatus();
        

        Parameters

        None.

         

        Error Codes (ADP_RET_CODE data type)

        Value

        Meaning

        ADP_AUTHORIZED

        The application is authorized to run.

        ADP_NOT_AUTHORIZED

        The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

        ADP_AUTHORIZATION_EXPIRED

        The application’s license has expired. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

        ADP_TIMEOUT

        Operation failed because the connection between the SDK and the Intel AppUp center client software timed out.

          

        Notes

        • The recommended method of determining authorization status after initial authorization is via a developer-created local variable. GetAuthorizationStatus is provided only for legacy support with Beta versions of the SDK. Use of this call should be avoided for applications using V1.0 and later of the C/C++ SDK.

        GetAuthorizationStatus Call Code Example

        The following code example shows use of the GetAuthorizationStatus call.

        ApplicationId SampleApplication::id(ADP_DEBUG_APPLICATIONID);
        SampleApplication::SampleApplication(int dataIn) : Application(id) {
                // use the ApplicationId from directly above
                this->dataLocal = dataIn;
                // set the local member variable dataLocal using the value of dataIn
        };
        void SampleApplication::PrintAuthorizationStatus() {
                ADP_RET_CODE ret = Application::GetAuthorizationStatus();
                if( ret  == ADP_AUTHORIZED)
                {
                        wcout << L"Application is authorized to run" << endl;
                }
                else
                {
                        wcout << L"Application authorization status for "
        << (string) id << ": " << ret << endl;
                }
        };
        int SampleApplication::GetData() {
                return dataLocal; //return the contents of the dataLocal member variable
        };
        

        Cleanup Code

        On application or process exit, the SDK library must be instructed to release the object and close the SDK library. The following code performs this cleanup.
         

        /// <ADP>
            if (myApplication != NULL){
                delete myApplication;
        myApplication = NULL;
        }
            return 0;
        /// </ADP>
        

        Instrumentation

        The SDK supports the following Instrumentation events to measure application usage:

        • Application Begin Event - Triggers sending a Begin Event message to the Intel AppUp center for the application.

        • Application End Event - Triggers sending an End Event message to the Intel AppUp center for the application.

        A usage record is only generated when a Begin Event is followed eventually by an End Event. A Begin Event alone does not cause a usage record to be generated.

        Begin Event Call

        Insert the BeginEvent call at the point where you wish to trigger the Begin Event. It is recommended to insert it in the same sequence as, and immediately after, the Application Constructor call. This starts usage measurement when the application is first authorized and allows the BeginEvent call to share the same exception handler as the Application Constructor call.

        Syntax

        try {
            myApp->BeginEvent();
            }
        

        Parameters

        myApp:  name of the object (the application)

        If the BeginEvent call is successful, then a Begin Event message is triggered. Otherwise an exception is thrown. The following exception is supported:

        • AdpRuntimeException - Failure in the general runtime environment.

          

        Error Codes (ADP_RET_CODE data type)

        Value

        Meaning

        ADP_FAILURE

        Operating was unsuccessful.

        ADP_NOT_INITIALIZED

        Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.

        ADP_NOT_AUTHORIZED

        The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

          

        Notes

        • A BeginEvent call must be preceded by a successful Application Constructor call or an exception is thrown.

        • A sensible approach to handling the first occurence of an ADP_FAILURE return code (in critical situations) is to attempt the authorization sequence. This may re-establish a valid session with the Intel AppUp center software.

        Code Example

        The following example shows the use of the BeginEvent call. A basic exception handler is used.

        #include "adpcppf.h"
        #include <iostream>
        int main( int argc, char** argv ) {
            try {
                Application *myApp = new Application(ApplicationId::DEBUG_ID );
                myApp->BeginEvent();
            }
            catch (AdpErrorException& e) {
                    // Your code to handle exceptions
                    wcout << L"Caught exception in application: " <<
                         e.what() << endl;
            }
        
            /// Application code goes here
        
        }
        

         

        End Event Call

        End Events must be preceded by Begin Events, or an exception is thrown. The EndEvent call is typically used as part of the application shutdown sequence.

        Syntax

        try {
            myApp->EndEvent();
        }
        

        Parameters

           myApp:  name of the object (the application)

        If the EndEvent call is successful, then an End Event message is triggered. Otherwise an exception is thrown. The following exception is supported:

        • AdpRuntimeException - Failure in the general runtime environment.

        • AdpWarningException - A warning condition was detected, such as no prior BeginEvent call.

          

        Error Codes (ADP_RET_CODE data type)

        Value

        Meaning

        ADP_FAILURE

        Operation was unsuccessful.

        ADP_NOT_INITIALIZED

        Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.

        ADP_NOT_AUTHORIZED

        The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

        ADP_NO_APP_BEGIN_EVENT

        Operation failed because an End Event has been attempted with no prior Begin Event. A Begin Event call must precede an End Event call in the application.

          

        Notes

        • An EndEvent call must be preceded by a BeginEvent call call or a warning exception is thrown.

        • A sensible approach to handling the first occurrence of an ADP_FAILURE return code (in critical situations) is to attempt the authorization sequence. This may re-establish a valid session with the Intel AppUp center software.

        Code Example

        The following example shows the use of the EndEvent call. The code triggers an End Event message and includes exception handlers for AdpRuntimeException and AdpWarningException.

         

           // Application code goes here
        
            try {
                myApp->EndEvent();
            }
            catch (AdpRuntimeException& e) {
                    // Your code to handle EndEvent errors
                    wcout << L"Caught EndEvent exception in application:
                         " << e.code() << endl;
            }
            catch (AdpWarningException& e) {
                    // Your code to handle EndEvent warnings
                    wcout << L"Caught EndEvent warning in application:
                         " << e.code() << endl;
            }
            // Application code goes here
        

        In-App Purchase APIs

        The Intel AppUp SDK library provides a family of APIs to support functions such as in-app upgrades, purchases, etc. When the appropriate API calls are included in applications, end users can upgrade their application, turn on additional features, game levels, etc., from within the application. The supported APIs and their typical usages are as follows:

        In-App Upgrade

        The Intel AppUp SDK library provides an API call to support upgrading to one designated version of an application. Typical usage of this In-Application Upgrade call is to support scenarios such as a user upgrading to a premium version of an application from a free version of the application. When invoked, the In-Application Upgrade call passes the Application ID of the target application to the Intel AppUp center software. The Intel AppUp center software then offers the upgrade to the end user. If the end user accepts the offer, the Intel AppUp center software installs the target version of the application (in addition to the original version). If the end user declines the offer, the existing version of the application continues running.

        Syntax

            app->Upgrade(TargetApplicationId);

        Parameters

        app:  name of the application object

        TargetApplicationId:  a Production Application GUID (see Target Application ID discussion later).

        If the Upgrade Authorization returns successfully, then the application can continue (the Intel AppUp center software will typically start an upgrade). Otherwise an exception is thrown, as follows:

        • AdpRuntimeException - Failure in the general runtime environment.

         

        Error Codes (ADP_RET_CODE data type)

        Value

        Meaning

        ADP_FAILURE

        Operation was unsuccessful. It can also indicate that more than one instantiation of the application was attempted.

        ADP_NOT_INITIALIZED

        Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.

        ADP_NOT_AUTHORIZED

        The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

         

        Target Application ID

        In general, the Application ID is a unique identifier for Intel AppUp center applications. The In-Application Upgrade call uses a Production Application ID to represent the target application. This Production Application ID does not need to be the actual Production ID during development. But the actual Production Application ID must be included prior to uploading your application to the Intel Developer Zone portal. As a mnemonic device, it may be helpful to use the Production Application ID of the original application as the target application during development.

        Notes

        • A sensible approach to handling an ADP_FAILURE error during the first authorization attempt is to attempt authorization again.

        • The target application must be: (1) already validated and in the Intel AppUp center, or (2) submitted with the original application for validation.

        Code Example

        The following example shows the In-Application Upgrade call with a Production Application ID and error and warning exception handlers. The sample includes extra lines of code to support a GUI with buttons and a message window.

         

            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("Caught ADP Runtime exception in application with
                    Exception Code: %1!ld!") , e.code());
                MessageBox(eMsg, _T("Exception Message"));
                AfxMessageBox(eMsg, MB_OK , 0);
                pWnd->SetWindowText(eMsg);
            }
            catch(AdpWarningException& e){
                CString eMsg;
                CWnd* pWnd = GetDlgItem(IDC_AdpStatus);
                eMsg.FormatMessage( _T("Caught ADP Warning exception in application with
                    Exception Code: %1!ld!") , e.code());
                MessageBox(eMsg, _T("Warning Message"));
                AfxMessageBox(eMsg, MB_OK , 0);
                pWnd->SetWindowText(eMsg);
            }
         

        In-App Unlocking

        The Intel AppUp SDK library provides an API to enable Intel AppUp® applications to receive payment for capabilities that were pre-built into the application, after the application has been installed and used by the end user.

        Unlocking advanced game levels is a typical use case for this API. For example, an end user installs a game application and can play the first three levels for free, but to play the higher game levels, the user has to purchase them. The Intel AppUp® In-App Unlocking API does not support downloading of new content. Effectively it allows unlocking of existing application capabilities. In this release, the API supports only non-consumable items (such as game level); it does not support consumable items (such as buying extra 1000 rockets). You can simulate consumable items by using a group of non-consumable items, but this requires extra effort and is outside the scope of this document.

        The application prompts the user to purchase a pre-built item. If the user decides to purchase the item, the following calls are processed:

        1. The application makes a call to the Intel AppUp® In-App Unlocking API, the request is sent to the Intel AppUp center.

        2. The Intel AppUp center displays a confirmation dialog box to the user with the item title, its price and currency.

        3. The user confirms the purchase. If user is not logged-in, the following happens:

          1. The Intel AppUp center displays the AppUp logon dialog box to the user.
            If the user has not provided its billing information yet, the Intel AppUp center forwards the end user to the page that enables the user to setup her billing info.

          2. After the user completes logging in and setting up the billing information,  The Intel AppUp center submits a purchase request to the Intel AppUp center backend.

        4. After the purchase is completed and confirmed, the end-user can continue to use the application with the purchased item enabled.

        The following In-App unlocking classes are included in the SDK C++ framework.

        Application Class Details

        Application: represents the Intel AppUp application instance.

        Methods

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

        Create an AppItemIF instance which presents an application item. The application must be successfully authorized before calling this API.

        Parameters

        id: Developer specified id of the application item

        locale: Application locale

        bRefresh: Optional, a Boolean flag, when set will force update of the item metadata, default value is false

        Return Values

        • InAppItemException - Operation failed to create item based on parameters.
        • AdpRuntimeException - Failure in the general runtime environment.

        Remarks

        The application must be successfully authorized before calling this function.

        This function will only work in the online state, and it can be called to get an AppItemIF object which is used to purchase an application item.

        Error Codes

        Value

        Meaning

        ADP_INVALID_DEVID

        Invalid developer supplied Id.

        ADP_INVALID_LOCALE

        Invalid locale.

        ADP_OFFLINE

        Device is offline

        ADP_APP_NOTAVAILABLE

        The application is not available.

        ADP_ITEM_NOTAVAILABLE

        The requested application item is not available.

        ADP_USER_NOTIDENTIFIED

        The user is not identified.

        ADP_TIMEOUT

        Operation timeout.

        ADP_FAILURE

        A general error occured that is not covered by the above error codes.

         

        bool Application::IsAppItemPurchased(const wchar_t* id)

        Check whether the application item had been purchased. The application must be successfully authorized before calling this API.

        Parameters

        id: Developer specified id of the application item

        Return Values

        The return value is true if the item is purchased. Otherwise the return value is false.

        Remarks

        The application must be successfully authorized before calling this API.

        This function works in either an online or offline state, it can be used to determine whether an application item is purchased or not.

        AppItemIF Class Details

        AppItemIF: Abstract class which represents an application item.

        Methods

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

        Returns the value of the requested item’s property. The returned value can be an empty string.

        Parameters

        propId: Property name. Valid values are defined in <AppUpSdkInstallDir>/Cpp/Include/adpcore.h as macros: : ITEM_GUID, ITEM_LOCALE, ITEM_ID, ITEM_TITLE, ITEM_DESC, ITEM_PRICE, ITEM_CURRENCY, ITEM_TOKEN

        Return Value

        The value of the requested property.

         

        virtual wstring AppItemIF::GetSignedToken()

        Returns the signed token of the requested purchased property. The returned value can be an empty string.

        Parameters

        None

        Return Value

        The signed token of this application item.

         

        virtual bool AppItemItem::IsPurchased()

        Checks whether the item has been purchased.

        Parameters

        None

        Return Values

        The return value is true if the item is purchased. Otherwise the return value is false.

         

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

        Purchase and application item. The provided price and currency are compared with the corresponding item metadata at the Intel AppUp center backend. The operation fails if they do not match.

        Parameters

        price  Price of the item to be purchased

        Currency Currency of the item to be purchased

        Return Values

        • InAppItemException - Operation failed.
        • AdpRuntimeException - Failure in the general runtime environment.

        Remarks

        The provided price and currency are compared with the corresponding item metadata at the Intel AppUp center backend. The operation fails if they don’t match.

        For the price and currency parameters, it is recommended to use the values returned from AppItemIF::GetProperty() function. If the currency value is mismatched with the user's billing information, this operation fails.

        Error Codes

        Value

        Meaning

        ADP_INVALID_PRICE

        Invalid price

        ADP_INVALID_CURRENCY

        Invalid currency

        ADP_OFFLINE

        Intel AppUp backend is offline

        ADP_USERCANCEL

        The user canceled the purchase

        ADP_APP_NOTAVAILABLE

        The application is not available

        ADP_ITEM_NOTAVAILABLE

        The requested application item is not available

        ADP_PRICE_CURRENCY_MISMATCH

        The price or currency do not match

        ADP_ALREADY_PURCHASED

        The requested application item was already purchased

        ADP_USER_NOTIDENTIFIED

        The user is not identified

        ADP_TIMEOUT

        Operation timeout

        In-App Unlocking Call Code Example

        The following example shows the typical usage of how to create an application item and purchase it.

        #include "adpcppf.h"
        #include <iostream>
        using namespace std;
        int _tmain(int argc, _TCHAR* argv[])
        {
          wcout << L"ADP API Version: " << ADP_API_VERSION <<endl;
          Intel::Adp::Application *pInAppUnlockingSampleApp = NULL;
          AppItemIF *pItemIf = NULL;
          try{
            pInAppUnlockingSampleApp = new Application(ADP_DEBUG_APPLICATIONID);
            // call Application::IsAppItemPurchased(const wchar_t* id)
            // to check whether the InAppItem is purchased
            if(pInAppUnlockingSampleApp->IsAppItemPurchased(L"level3"))
              wcout << L"level3 is purchased already." << endl;
            else
              wcout << L"level3 is not purchased yet." << endl;
            //change the developer id and locale here to adjust your item metadata.
            pItemIf = pInAppUnlockingSampleApp->CreateInAppItem(L"level3", L"en-US", true);
            wcout << L"Create app item was successful" << endl;
            wcout << L"Item GUID: "<<pItemIf->GetProperty(ITEM_GUID)<< endl;
            wcout << L"Item Locale: "<<pItemIf->GetProperty(ITEM_LOCALE)<< endl;
            wcout << L"Item Developer Supplied ID: "<<pItemIf->GetProperty(ITEM_ID)<< endl;
            wcout << L"Item Short ItemName: "<<pItemIf->GetProperty(ITEM_DESC)<< endl;
            wcout << L"Item Price: "<<pItemIf->GetProperty(ITEM_PRICE)<< endl;
            wcout << L"Item Currency: "<<pItemIf->GetProperty(ITEM_CURRENCY)<< endl;
            wcout << L"Get Item properties was successful" << endl;
            wcout << L"Item has "<< (pItemIf->IsPurchased() ? "" : "not ") <<"been purchased"<< endl;
            //change the price or currency to adjust your item metadata
            bool bPurchased = pItemIf->Purchase(pItemIf->GetProperty(ITEM_PRICE).c_str(), pItemIf->GetProperty(ITEM_CURRENCY).c_str());
            if(bPurchased)
            wcout << L"Item purchase was successful" <<endl;
            wcout << L"Item Token:" << pItemIf->GetSignedToken() << endl;
            wcout << L"Get Item token was successful" << endl;
            }
            catch (Intel::Adp::InitializationException& e) {
            wcout << L"Caught Initialization exception in application with exception code: " << e.code() << endl;
            }
          catch (Intel::Adp::UnauthorizedException& e) {
            wcout << L"Caught Unauthorized exception in application with exception code: " << e.code() << endl;
          }
          catch (Intel::Adp::AdpRuntimeException& e) {
            wcout << L"Caught Runtime exception in application with exception code: " << e.code() << endl;
          }
          catch (Intel::Adp::InAppItemException& e) {
            wcout << L"Caught InAppItem exception in application with exception code: " << e.code() << endl;
          }
          //delete Application Item pointer
          if(pItemIf)
          {
          delete pItemIf;
          pItemIf = NULL;
          }
          // delete Application pointer
          if(pInAppUnlockingSampleApp != NULL){
            delete pInAppUnlockingSampleApp;
            pInAppUnlockingSampleApp = NULL;
          }
          return 0;
        }
        

        Consumer Identity Service Call

        The Consumer Identity Service API enables the application to log into an application with a third party identity provider such as Facebook*, or Google*. After successful login, the application can obtain the ’normalized’ identity token, in the standard format defined by Intel.

        The typical usage of this API includes the following steps:

        1. Invoke the GetIdentityProviders function to the get the supported identity providers and display them on the application login page.

        2. The end user selects an identity provider to log in

        3. The application invokes the Login function to open the identity provider’s login page in default browser, and then waits for a callback function to be invoked by Consumer Identity Service.

        4. The end user fills in his account credentials and grants access rights to the application

        5. The callback function is invoked to notify application that the normalized token is ready.

        6. The application calls GetIdentityToken function to obtain the normalized token.

        NOTE: The target application must be validated and in the Intel AppUp center

        IdentityProvider Class Details

        IdentityProvider: Provides the APIs to construct Identity Provider object and query the properties of identity provider.

        Constructor

        Methods

        std:wstring GetName() const

        Return Values

        The name of identity provider.

         

        std:wstring GetIconURI() const

        Return Values

        The URI of identity provider icon.

        IdentityToken Class Details

        IdentityToken: Provides the APIs to construct Identity Token object and query the properties of a normalized identity token.

        Constructor

        Methods

        std:wstring GetFirstName() const

        Return Values

        The first name of the end user.

         

        std:wstring GetLastName() const

        Return Values

        The last name of the end user.

         

        std:wstring GetEmail() const

        Return Values

        The email address of the end user.

         

        std:wstring GetTimestamp() const

        Return Values

        The time stamp of the token.

         

        std:wstring GetExpDate() const

        Return Values

        The expiration date of the token.

         

        std:wstring GetIdentity() const

        Return Values

        The identity of the token.

         

        std:wstring GetIdentityProvider() const

        Return Values

        The public identity of the identity provider.

         

        std:wstring GetToken() const

        Return Values

        The normalized token in XML format.

        ConsumerIdentityService Class Details

        ConsumerIdentityService: Provides the APIs to get identity providers list, start the login session and obtain the normalized identity token.

        Constructor

        The object of Consumer Identity Service can only be obtained by the method defined in Application class: ConsumerIdentityService* GetConsumerIdentityService() const.

        There is only one instance of Consumer Identity Service object in one process scope. If function is called multiple times, the same pointer to the Consumer Identity Service object is returned.

        Application should NOT dereference this pointer as it will be dereferenced by the destructor of the Application class.

        Return Values

        If the function succeeds, the return value is the object of the Consumer Identity Service. Otherwise the following exception is thrown:

        • UnauthorizedException - Failure while attempting to call this function before the Application object was onstructed.

        Error Codes

        Value

        Meaning

        ADP_NOT_AVAILABLE

        ADP_NOT_AVAILABLE

        ADP_FAILURE

        Operation was unsuccessful. It can also indicate that more than one instantiation of the application was attempted.

        ADP_NOT_INITIALIZED

        Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.

        ADP_INCOMPATIBLE_VERSION

        Operation failed because the API version of the application is not supported by the current Intel AppUp center software.

        ADP_NOT_AUTHORIZED

        The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, or allowing the application to run with limited functionality.

        ADP_AUTHORIZATION_EXPIRED

        The application’s license has expired. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, or allowing the application to run with limited functionality.

        ADP_TIMEOUT

        Operation failed because the connection between the SDK and the Intel AppUp center client software timed out.

        Methods

        std::vector<Intel::Adp::ConsumerIdentity::IdentityProvider> GetIdentityProviders()

        Return Values

        If the function succeeds, the return value is the list of supported identity provider objects. Otherwise an exception is thrown. The following exceptions are supported:

        • InvalidIdentityProviderException - Failure due to invalid or incomplete identity provider data.

        • AdpRuntimeException - Failure while attempting to call this function before the Consumer Identity Service object constructed.

        Error Codes

        Value

        Meaning

        ADP_CI_INVALID_IDENTITY_PROVIDER

        Invalid or incomplete identity provider data.

        ADP_FAILURE

        A general error occurs that is not covered by above error codes.

         

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

        Start a new login session. This function will open a new tab of the default browser and navigate to the login page of the identity provider.

        The Consumer Identity Service APIs support both synchronous and asynchronous ways to get the normalized identity token. To use this API in synchronous way, pass NULL to pCallbackProc parameter. To use this API in asynchronous way, pass a valid pointer to callback function to pCallbackProc parameter.

        This API enables the application to automatically bring its main window to foreground window before GetIdentityToken return. To enable this feature, pass true to the bringAppToForeground parameter. To disable this feature, pass false to the bringAppToForeground parameter.

        As there is only one login session allowed in one process, to start another login session, you must wait for the previous login session to complete, or explicitly call Cancel function, before you call this function again.

        Parameters

        identityProvider: The reference of identity provider object that the end user selected to login to.

        pCallbackProc: The pointer to the application-defined function to be used to notify the application that the login session is completed. For more information on the callback function, see LoginCallbackProc.

        pParameter: A pointer to an application-defined variable to be passed to the callback function. If pCallbackProc is NULL, this parameter is ignored.

        bringAppToForeground (optional): Indicates whether application wants the SDK bring its main window to foreground window after the login session completed.

        Return Values

        If the function succeeds, a new tab of the default browser opens on the login page of identity provider. Otherwise an exception is thrown. The following exceptions are supported:

        • InvalidOperationException - Failure while attempting to call this function before the previous login session is completed or canceled.

        • AdpRuntimeException - Failure while attempting to call this function before the Consumer Identity Service object constructed.

        Error Codes

        Value

        Meaning

        ADP_CI_INVALID_OPERATION

        You started a new login session before the previous login session completed or canceled

        ADP_FAILURE

        A general error occurs that is not covered by above error code.

         

        void cancel()

        Cancel the current login session. The application must call this function to cancel the current login session before making another call to the Login function to start another login session.

        There is no exception thrown even if call this function after current login session already completed or if you call this function multiple times.

        Return Values

        If the function succeeds, the current login session will be canceled. Otherwise an exception is thrown. The following exceptions are supported:

        • AdpRuntimeException - Failure while attempting to call this function before the Consumer Identity Service object constructed.

        Error Codes

        Value

        Meaning

        ADP_FAILURE

        A general error occurred.

         

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

        This API will block the calling thread of an application until the normalized identity token is received from Intel Identity Service, or an error occurs.

        Return Values

        If the function succeeds, a new instance of normalized identity token is constructed and returned.. Otherwise an exception is thrown. The following exceptions are supported:

        • UserAccessDenyException - The end user didnot grant access rights to the application.

        • RequestTimeoutException - The end user did not complete the login within a certain period (the default value is 300 seconds).

        • InvalidIdentityTokenException - Invalid or incomplete normalized identity token data from Intel identity service.

        • InvalidIdentityTokenSignatureException - The integrity of the normalized identity token signature was not verified.

        • InvalidOperationException - Failure due to a call to this function before calling the Login() function.

        • AdpRuntimeException - Failure due to an attempt to call this function before constructing the Consumer Identity Service object.

        Error Codes

        Value

        Meaning

        ADP_CI_USER_ACCESS_DENY

        The end user did not grant access rights to the application

        ADP_CI_REQUEST_TIMEOUT

        The end user did not complete the login within the time limit (the default time limit is 300 seconds)

        ADP_CI_INVALID_IDENTITY_TOKEN

        Invalid or incomplete identity token data

        ADP_CI_INVALID_IDENTITY_TOKEN_SIGNATURE

        The signature verification of normalized identity token failed

        ADP_CI_INVALID_OPERATION

        This function was called before a Login function

        ADP_FAILURE

        A general error occurs that is not covered by above error codes

        LoginCallbackProc Details

        LoginCallbackProc: A placeholder for an application-defined function that serves as the callback function, used by the Consumer Identity Service to notify the application that a login session is completed.

        Syntax

        void LoginCallbackProc(void* pParameter)

        This function is called by the Consumer Identity Service when the login session successfully completed, or an error occurred. Once this function is invoked, application should call ConsumerIdentityService::GetIdentityToken() function to obtain the normalized token or the specific error code that is embedded in an exception.

        This function is not called if the application explicitly calls ConsumerIdentityService::Cancel() function to cancel a login session.

        Parameters

        pParameter: The pointer to an application-defined variable that is passed to the ConsumerIdentityService::Login() function.

        Error Codes

        Value

        Meaning

        ADP_CI_INVALID_IDENTITY_PROVIDER

        The identity provider data from Intel Identity Service is invalid or incomplete

        ADP_CI_INVALID_IDENTITY_TOKEN

        The normalized identity token data from Intel Identity Service is invalid or incomplete

        ADP_CI_INVALID_IDENTITY_TOKEN_SIGNATURE

        The signature verification of the normalized identity token failed

        ADP_CI_REQUEST_TIMEOUT

        End user does not complete the login within the time limit.

        ADP_CI_USER_ACCESS_DENY

        The end user does not grant access rights to application.

        ADP_CI_INVALID_OPERATION

        Application calls Consumer Identity Service APIs in an unexpected sequence.

        ADP_FAILURE

        A general error occurs that is not covered by above error codes.

        Consumer Identity Service Call Code Example

        The following example shows the typical usage of Consumer Identity Service call.

        #include "adpcppf.h"
        #include <iostream>
        using namespace std;
        static Intel::Adp::Application *g_pCISampleApp = NULL;
        void LoginCallBack(void*)
        {
          try {
            if (g_pCISampleApp != NULL) {
              // Get the consumer identity service instance
              ConsumerIdentityService* pService = g_pCISampleApp->GetConsumerIdentityService();
              // Get the instance of IdentityToken object.
              IdentityToken token = pService->GetIdentityToken();
              // Query properties of identity token here
            }
          }
          // Exception handler goes here
        }
        int _tmain(int argc, _TCHAR* argv[])
        {
          // Application authentication
          try {
            g_pCISampleApp = new Application(ADP_DEBUG_APPLICATIONID);
          }
          // Exception handler goes here
          // Consumer Identity Service call
          ConsumerIdentityService* pService = NULL;
          try{
            // Get the consumer identity service instance
            pService = g_pCISampleApp->GetConsumerIdentityService();
            // Get a list of IdentityProvider objects which are supported by Intel identity service.
            vector<IdentityProvider> providers = pService->GetIdentityProviders();
            // Start to log in with the first identity provider
            pService->Login(providers[0], LoginCallBack, NULL);
          }
          // Exception handler goes here
          // Delete application pointer
          if (g_pCISampleApp != NULL){
            delete g_pCISampleApp;
            g_pCISampleApp = NULL;
          }
          return 0;
        }
        

        Crash Reporting

        The Intel AppUpSDK library supports Crash Reporting to provide a snapshot of the state of the application when a crash occurs. Default crash reports are automatically enabled when the application constructor runs; you do not have to explicitly enable this capability. Default crash reports are viewable via My Dashboard on the Intel Developer Zone portal. This information includes application context information, runtime environment information, SDK identification information, and a core stack dump. The complete report can be viewed by clicking on the Details link for a specific report.

        The Intel AppUp® Software Development Kit Developer Guide for C++ provides more information on My Dashboard and how Crash Reporting works at the client system level.

        Customized Crash Reporting allows you to provide different information than default Crash Reporting. Customized Crash Reporting is implemented by defining a crash report class MyCrashReport derived from the SDK DefaultCrashReport class. Then setting MyCrashReport (or any other object derived from DefaultCrashReport) in the source code automatically disables default Crash Reporting.

        The table below lists the possible fields in a crash report, with the Source column defining the source (SDK or Developer) of the information for the respective field. As a developer, you can modify the fields where the Source is listed as Developer. Fields are modified by overriding the default field.

        Note:  It is your responsibility to ensure that custom Crash Reports do not include any data that violates Intel Privacy rules. See http://software.intel.com/en-us/appup for details.

         

        Custom Crash Report Fields and Sources

        Crash Report Fields

        My Dashboard Column

        Source

        Application Name

        No (but included in Details)

        SDK

        Application ID

        No (but included in Details)

        SDK

        ModuleName

        Module (and in Details)

        Developer

        LineNumber

        Line (and in Details)

        Developer

        Category

        No (but included in Details)

        Developer

        Message

        Messages (and in Details)

        Developer

        ErrorData

        No (but included in Details)

        Developer

        SDK API Level

        No (but included in Details)

        SDK

        Runtime

        Runtime (and in Details)

        SDK

        Runtime version

        No (but included in Details)

        SDK

        OS

        OS (and in Details)

        SDK

        OS version

        No (but included in Details)

        SDK

        Timestamp

        Timestamp (and in Details)

        SDK

        Up to 20 custom fields

        (reserved for future use)

        Developer

          

        Custom crash reports are set immediately after the SDK Application Constructor call so that crash reports can include data as early in application execution as is reasonably possible.

        The fields with the greatest flexibility for customization are listed below:

        • The Category field allows you to create categories to sort your crash reports on the Intel Developer Zone portal. For example, you may wish to create categories called "MEMORY”, "IO”, "USER ERROR”, etc.

        • The Error Data field allows you to create your own stack dumps or long error messages to help you understand why your application crashed.

        Note: Some crashes can lead to a client system eventually halting. In these cases, the time to store a crash report on the client system may be limited. To maximize obtaining crash information, you should consider the tradeoffs between the amount of information to include in a custom crash report versus a potentially narrow window of time to store the information on the client system.

          

        Crash Reporting Class Structure

        The following crash reporting classes are included in the SDK C++ framework.

        AbstractCrashReport

        AbstractCrashReport is an abstract class with pure virtual methods that are designed to populate data existing within the class. Since the system may be at an unstable state, allocation of data on the stack is to be avoided, if possible. These methods will be called by the underlying framework to collect data to be submitted in crash reports. By implementing a subclass of AbstractCrashReport, you can gain control of every field that will be returned during the crash reporting process. However, you are also required to implement every field.

        DefaultCrashReport

        The DefaultCrashReport class is a reference implementation of the AbstractCrashReport class and is installed by default. This default implementation performs best-effort collection of data that should be appropriate and accurate in most cases. However, you may subclass DefaultCrashReport to customize one or more fields.

        AdvancedCrashReport (Microsoft Windows* only)

        The AdvancedCrashReport class provides an advanced implementation of the AbstractCrashReport class. This implementation leverages a class AdvancedCallStack, which inherits from CallStack, and provides full callstack presentation (module, symbol, line number). To provide these enhanced capabilities AdvancedCrashReport class utilizes the DbgHelp utility library distributed as part of the Microsoft Debugging Tools for Windows* package.

        AbstractCrashReport Details

        AbstractCrashReport is the base class from which all crash reports are derived. You may inherit from AbstractCrashReport as long as you implement every method in the class. (Alternatively you can extend the DefaultCrashReport class if you only want to override some of these methods.) The C ADP_ReportCrash is developed against the following signature:

            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
            };
        

        The arguments below have been declared in AbstractCrashReport as member variables with the following names:

            wchar_t module[80];
            wchar_t message[80];
            wchar_t category[80];
            wchar_t errorData[4000];
            long    lineNumber;
            ADP_CrashReportField* pCrashReportFields;
            long    crashReportFieldCount;
        

        If you wish to provide customized unhandled crash reporting you need to override the pure abstract methods in AbstractCrashReport, populating these variables. (These variables, in turn, are used in the call to the C ADP_ReportCrash.)

        The AbstractCrashReport class offers the following virtual overrides

             virtual void PopulateModuleName()

             This method is provided to populate the AbstractCrashReport::module member variable.

             virtual void PopulateLineNumber()

             This method is provided to populate the AbstractCrashReport::lineNumber member variable.

             virtual void PopulateMessage()

             This method is provided to populate the AbstractCrashReport::message member variable

             virtual void PopulateCategory()

             This method is provided to populate the AbstractCrashReport::category member variable.

             virtual void PopulateErrorData()

             This method is provided to populate the AbstractCrashReport::errorData member variable.

             virtual void PopulateCrashReportFields()

             This method is provided to populate the AbstractCrashReport:: pCrashReportFields
        and AbstractCrashReport::crashReportFieldCount member variables.

        The arguments below have been declared in AbstractCrashReport as member variables with the following names:

            protected StringBuffer errorData = new StringBuffer();
            protected String errorMessage = "";
            protected String errorModule = "";
            protected long errorLine = 0;
            protected String errorCategory = "";
            protected AdpCrashReportField[] crashReportFields = null;
        

        DefaultCrashReport Details

        The DefaultCrashReport class provides a reference implementation of the AbstractCrashReport class. This implementation leverages a class CallStack, which is provided for your use as an hpp file. In this configuration, all business logic is exposed as a header file, and all methods of the class are declared inline. CallStack attempts to traverse the callstack of the calling thread, compiling information on each stack frame into CallStackEntry structures, and storing each into an STL templated list container. See the Intel AppUp® Software Development Kit Developer Guide for C++ for a custom report example based on DefaultCrashReport. The structure of a CallStackEntry is as follows:

            struct CallStackEntry {
                   wstring fileName;
                   wstring moduleName;
                   wstring symbolName;
                   unsigned long lineNumber;
                   void* pAddress;
         
                   CallStackEntry();
                   wstring str();
           };
        

        CallStack Details

        CallStack utilizes the Win32 API CONTEXT structure, along with pointer arithmetic, to traverse the stack and populate the CallStackEntryList with a set representing the stack frames of a given thread.

        CallStack features a no argument, default constructor, which initializes the object's internal variables. When you need the CallStack class to record the state of a calling thread's stack, the developer will invoke the CallStack::Parse method. For Win32 environments, the CallStack::Parse method takes a CONTEXT structure. To retrieve this record arbitrarily, you can invoke the Win32 library method ::RtlCaptureContext.
         

            // Execute CallStack::Parse for Win32 at an arbitrary execution
            // point.
            CallStack callStack;
            CONTEXT context;
            ::RtlCaptureContext(&context);
         
            CallStackEntryList entries = callStack.Parse(&context);
        

        CallStackEntryList&  Parse()

        Parses the calling thread's call stack, saving the information in an STL collection list CallStackEntry.

        Parameters

             None

        Exceptions

             None

        Returns

        Value

        Description

        CallStackEntryList&

        A reference to the CallStackEntryList maintained by the CallStack object.

        CallStackEntryList&  GetEntries()

        Returns a reference to the CallStackEntryList maintained by the CallStack object.

        Parameters

             None

        Exceptions

             None

        Returns

        Value

        Description

        CallStackEntryList&

        A reference to the CallStackEntryList maintained by the CallStack object.

        AdvancedCrashReport Details

        The AdvancedCrashReport class provides an advanced implementation of the AbstractCrashReport class. This implementation leverages a class AdvancedCallStack, which inherits from CallStack, and provides full callstack presentation (module, symbol, line number). To provide these enhanced capabilities, AdvancedCrashReport class uses the DbgHelp utility library distributed as part of the Microsoft Debugging Tools for Windows* OS package.

        The full set of steps required to enable AdvancedCrashReport is as follows:

        • Download and install the latest version of Microsoft Debugging Tools for Windows* package.

        • Define _ADP_ADVANCED_CRASHREPORT pre-processor symbol in the application project file.

        • Include AdvancedCrashReport.h header file with your application.

        • Add dbghelp.lib library to the list of libraries the application links with.

        The system DbgHelp.dll is available on most Microsoft Windows* OS installations, however on the older systems its version might not be compatible with the version of the DbgHelp.lib, which was linked to the application. To ensure that the correct version of the DbgHelp.dll is available at runtime on the end user’s system developers may consider redistribution of DbgHelp.dll with their applications. Refer to the DbgHelp licensing documentation for terms and conditions of its redistribution.

        The following sample code shows how to install the AdvancedCrashReport handler for the application.

        #include "AdvancedCrashReport.h"
        &ldots;
        Application::SetCrashReport(new AdvancedCrashReport);
        ...  
        

        Exceptions

        The SDK library includes three pre-defined exception classes for errors and one pre-defined exception class for warnings to provide greater granularity in exception handling. These exception classes are as follows:

        Error Exception Classes
        • InitializationException - Catches error exceptions thrown while the SDK library application constructor attempts to initialize the SDK library code. This class is derived from AdpErrorException.

        • UnauthorizedException - Catches error exceptions thrown while the SDK library code attempts to authorize the application. This class is derived from AdpErrorException.

        • AdpRuntimeException - Catches general runtime error exceptions while executing SDK library code. This class is derived from AdpErrorException.

        Warning Exception Class
        • AdpWarningException - Catches warning exceptions while executing SDK library code.

        Note that the AdpErrorException is the base class for the three Error Exception classes, as shown below. AdpErrorException and AdpWarningException are both derived from the same base class, AdpException.

        The following subsections describe these exception classes in detail.

        InitializationException

        Represents an error during the initialization of the application. The error code helps specify the cause of the initialization error exception. Once initialization completes, this exception will not occur.

        UnauthorizedException

        Represents a failure to cleanly authorize an application. The error code helps specify the cause of the authorization error exception. Once authorization completes, this exception will not occur.

        AdpRuntimeException

        Represents an underlying core library error. The error code helps specify the cause of the runtime error exception. This exception can occur at any point after authorization.

        AdpWarningException

        This is the exception class for situations that are important, but not considered an error. An example is encountering an EndEvent call with no prior BeginEvent call. The return code helps specify the cause of the warning exception.

        Code Examples for Exceptions

        The following example shows the C++ catch sequence following an Application Constructor call. This sequence includes catches for the error and exception classes. See the EndEvent call earlier for an example of a catch for the warning exception class.

        const ApplicationId myApplicationID(0x12341234, 0x56785678, 0x12341234, 0x56785678);
         
        int main(int argc, char** argv)
            {
            Application * myApplication = NULL;
            try
            {
                myApplication = new Application(myApplicationID);
            }
            catch (InitializationException& e) {
                    // Your code to handle initialization exceptions
                    wcout << L"Caught Initialization exception in application: " << e << endl;
            }
            catch (UnauthorizedException& e) {
                    // Your code to handle authorization exceptions
                    wcout << L"Caught Unauthorized exception in application: " << e << endl;
            }
            catch (AdpRuntimeException& e) {
                    // Your code to handle runtime exceptions
                    wcout << L"Caught Runtime exception in application: " << e << endl;
            }
        }
        

        Return/Error Codes

        The following table is a comprehensive list of the return/error codes returned by SDK API calls to the calling routine, along with description of possible conditions that caused each code to be returned. Not every result code is returned for every API call. Refer to the information for a specific API call to see what codes may be returned for that call. (The information on a specific API call also may contain additional details on specific conditions that may cause a code to be returned for that call.)

        Results codes can be obtained from any of the exception classes by using the code() function in the message declaration.

         

        API Call Return/Error Codes

        Value

        Meaning

        ADP_SUCCESS

        Operation was successful.

        ADP_FAILURE

        Operation was unsuccessful.

        ADP_NOT_AVAILABLE

        Operation failed because the SDK library was not available. This can occur if the Intel AppUp center software is not installed properly.

        ADP_NOT_INITIALIZED

        Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.

        ADP_INCOMPATIBLE_VERSION

        Operation failed because the API version of the application is not supported by the current Intel AppUp center software.

        ADP_AUTHORIZED

        The application is authorized to run.

        ADP_NOT_AUTHORIZED

        The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

        ADP_AUTHORIZATION_EXPIRED

        The application’s license has expired. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

        ADP_NO_APP_BEGIN_EVENT

        Operation failed because an End Event has been attempted with no prior Begin Event. A Begin Event call must precede an End Event call in the application.

        ADP_TIMEOUT

        Operation failed because the connection between the SDK library and the Intel AppUp center client software timed out.

         

        End User Error Messages

        The SDK contains error message strings that can be retrieved by applications and displayed to end users. These messages are accessed via their unique Message ID. They do not map directly to the Return Codes.

        End User Error Messages

        Message ID

        Message Text

        String_ADP_AUTHORIZATION_EXPIRED

        The license for this application has expired.

        String_ADP_BEGINEVENT_ERROMSG

        The application experienced an error while starting a usage record.

        String_ADP_ENDEVENT_ERRORMSG

        The application experienced an error while ending a usage record.

        String_ADP_FAILURE

        The application experienced a critical error.

        String_ADP_INCOMPATIBLE_VERSION

        The current Intel AppUp center software does not support this version of the application.

        String_ADP_NO_APP_BEGIN_EVENT

        The application did not complete a start of usage record.

        String_ADP_NOT_AUTHORIZED

        The application is not authorized to run under this account on this device.

        String_ADP_NOT_AVAILABLE

        The application cannot connect to the Intel AppUp center.

        String_ADP_NOT_INITIALIZED

        The application did not initialize properly.

        String_ADP_TIMEOUT

        The Intel AppUp center response timed out.

        String_ADP_UPGRADE_ERRORMSG

        The application failed to send the upgrade request to the Intel AppUp center.

         

        Component Reference Information

        This section provides reference information on components. Code examples are provided, as appropriate.

        Note: An application is licensed to use a component if there is a pre-arranged agreement between the developer of the component and the developer of the application. It is the responsibility of you, the component developer, to enforce the license, i.e., to ensure that the calling application has a license to use your component.

        Component Guidelines

        The following guidelines address the unique aspects of developing components:

        • Components are supported by their own class in the SDK library, called Component. The Component class is based on a base Product class. The SDK supports either extending the Component class (inheritance) or using the component as a delegate to call the C++ framework. The recommended way of creating components is to extend the Component class (inheritance).

        • You must create the Application class before creating the Component class used in the application.

        • Multiple instances of a Component may exist within an Application. This results in component authorization being handled differently than application authorization, as follows:

          • Only the first instance of a component performs component authorization. If an UnauthorizedException occurs, the reason for the exception can be determined by catching the exception and reading the error code.

          • Subsequent instances of the component determine whether they can run or not by reading a developer-created, local variable that stores the status from the initial authorization, or by calling GetAuthorizationStatus. These methods are quicker than having subsequent component instances each perform their own authorization.

        • Each Component instance must be independently deleted.

        • Component IDs are different than Application IDs.

        • Exception handling for components is the same as for applications, except for the authorization differences described above.

        • Instrumentation (Begin Events and End Events) is not supported at the component level.

        • Crash Reporting is not supported at the component level.

        Component IDs

        The Component ID is a unique identifier for Intel AppUp center components. There are two types of Component IDs:  (1) a Debug Component ID, and (2) a Production Component ID. Debug Component IDs are used for testing. You must replace the Debug Component ID with a Production Component ID after testing in order to upload your application to the Intel Developer Zone portal.

        • Debug Component ID &emdash; During development, the Debug ID allows testing with the Intel AppUp Software Debugger. This Debug ID is a 128-bit number, expressed as a string using predefined constants. Two versions of a Debug ID exist:

          • ADP_DEBUG_COMPONENTID:  Used with the Intel AppUp Software Debugger to get an ADP_AUTHORIZED response back. This allows most of the application to be tested and debugged. The actual values of this Debug ID is contained in the SDK library.

          • ADP_EXPIRED_COMPONENTID:  Used with the Intel AppUp Software Debugger to get an ADP_AUTHORIZATION_EXPIRED response back. This allows the "expired” branch of the application to be tested and debugged. The actual values of this Debug ID is contained in the SDK library.

        • Production Component ID &emdash; Production IDs are obtained from the Intel Developer Zone portal, which requires that you enroll as an Intel AppUp developer. The Production ID is a 128-bit number organized as four integers in hex format.

        GetAuthorizationStatus Call for Components

        The GetAuthorizationStatus call provides legacy support for Beta versions of the SDK. This call allows an application to determine if a component is authorized to run after the initial authorization for the component. The return value shows the original authorization status of the component constructor at any point after the component constructor call has completed. (Read the Notes section prior to using this call.)

        Syntax

            static RETURN GetAuthorizationStatus();
        

        Parameters

        None.

          

        Error Codes (ADP_RET_CODE data type)

        Value

        Meaning

        ADP_AUTHORIZED

        The component is authorized to run.

        ADP_NOT_AUTHORIZED

        The component is not authorized to run. Components can choose how to respond, such as preventing an component from running, allowing the component to run for a grace period so the user can obtain a license, allowing the component to run with limited functionality, etc.

        ADP_AUTHORIZATION_EXPIRED

        The component’s license has expired. Components can choose how to respond, such as preventing an component from running, allowing the component to run for a grace period so the user can obtain a license, allowing the component to run with limited functionality, etc.

        ADP_TIMEOUT

        Operation failed because the connection between the SDK library and the Intel AppUp center client software timed out.

         

        Notes

        • The recommended method of determining authorization status after initial authorization is via a developer-created, local variable. GetAuthorizationStatus is provided only for legacy support with Beta versions of the SDK. Use of this call should be avoided for applications using V1.0 and later of the C++ SDK.

        • A sensible approach to handling an ADP_TIMEOUT error during the first authorization attempt is to attempt authorization again.

        Component Code Example

        The following example shows the code for a component that retireives and displays platform information. The component derives from the Component class and uses a Component Debug ID during development and test. (A Component Production ID must be inserted in place of the Debug ID prior to submitting the component to the Intel Developer Zone portal.)

        ##include "stdafx.h"
         
        // Use the DEBUG_ID when developing a component, but replace the following
        // with a valid ID obtained from the Developer Portal before submitting
         
        SampleComponent::SampleComponent(void): Component(ADP_DEBUG_COMPONENTID)
        {
         
        }
         
         
        SampleComponent::~SampleComponent(void)
        {
         
        }
         
         
        // This Component retrieves the Platform Information and prints it
         
        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("Intel Itanium Processor Family");
                break;
           case 9:
                strProcessArchitecture = _T("x64");
                break;
           case 0xffff:
           default:
                strProcessArchitecture = _T("Unknown architecture");
                break;
            }
            strPlatformInfo.FormatMessage( _T("Component Authorized to run.nn
                Hardware informationnnPage size: %1!u!n
                Number of processors: %2!u!n
                Processor Architecture: %3!s!n"),
                siSysInfo.dwPageSize,
                siSysInfo.dwNumberOfProcessors,
                strProcessArchitecture);
            pWnd->SetWindowTextW(strPlatformInfo);
        }
        

        Legal Information

        INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL(R) PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
        UNLESS OTHERWISE AGREED IN WRITING BY INTEL, THE INTEL PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE INTEL PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR.
        Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information.
        The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
        Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.
        Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548-4725, or by visiting Intel's Web Site.

        Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor family, not across different processor families. See http://www.intel.com/products/processor_number for details.

        For beta and pre-release product versions. This document contains information on products in the design phase of development.

        BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Atom, Centrino Atom Inside, Centrino Inside, Centrino logo, Core Inside, FlashFile, i960, InstantIP, Intel, Intel logo, Intel386, Intel486, IntelDX2, IntelDX4, IntelSX2, Intel Atom, Intel Atom Inside, Intel Core, Intel Inside, Intel Inside logo, Intel. Leap ahead., Intel. Leap ahead. logo, 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, and Xeon Inside are trademarks of Intel Corporation in the U.S. and other countries.

        *Other names and brands may be claimed as the property of others.

        Copyright (C) 2011, Intel Corporation. All rights reserved.

        Microsoft product screen shot(s) reprinted with permission from Microsoft Corporation.

        Para obter mais informações sobre otimizações de compiladores, consulte Aviso sobre otimizações.