Intel AppUp Software Development Kit API Reference for C++
SDK Version 2.0 Copyright © 2011 Intel Corporation. All Rights Reserved. Document Number: 324249-006US.
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.
Contents
Application Reference Information
Configuration and Build Information
GetAuthorizationStatus Call Code Example
Consumer Identity Service Call
Crash Reporting Class Structure
Component Reference Information
GetAuthorizationStatus Call for Components
About this Document
This document is for developers using the Intel AppUpTM 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 AppUpSM 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 AppUpSM center. These can be new applications/components or existing ones being ported for the Intel AppUpSM 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 AppUpTM Software Development Kit Developer Guide for C++ document, which is shipped with the Intel AppUpTM Software Development Kit for C/C++. The SDK is available on the Intel AppUpSM developer program 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 AppUpTM 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 AppUpSM 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:
The default pathname to the libraries is: Program Files/Intel/IntelAppUpSDK/Cpp/lib/.
|
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 |
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 AppUpSM developer program 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 AppUpSM 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 AppUpSM 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 AppUpSM 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 AppUpSM center client software timed out. |
Application IDs
The Application ID is a unique identifier for Intel AppUpSM developer program 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 AppUpSM developer program portal.
Debug Application ID - During development, the Application Debug ID allows testing with the Intel AppUpTM 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 AppUpTM 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 AppUpTM 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 AppUpSM developer program portal, which requires that you enroll in the Intel AppUpSM developer program. 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 AppUp(SM) Developer Program 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 AppUpSM 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 AppUpSM center for the application.
Application End Event - Triggers sending an End Event message to the Intel AppUpSM 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 AppUpSM 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 AppUpSM 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 AppUpTM 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 AppUpTM 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 AppUpSM center software. The Intel AppUpSM center software then offers the upgrade to the end user. If the end user accepts the offer, the Intel AppUpSM 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 AppUpSM 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 AppUpSM developer program 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 AppUpSM developer program 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 AppUpSM store, 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 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 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:
The application makes a call to the AppUp In-App Unlocking API, the request is sent to the Intel AppUp(SM) Center.
The Intel AppUp(SM) Center displays a confirmation dialog box to the user with the item title, its price and currency.
The user confirms the purchase. If user is not logged-in, the following happens:
The Intel AppUp(SM) Center displays the AppUp logon dialog box to the user.
If the user has not provided its billing information yet, the Intel AppUp(SM) Center forwards the end user to the page that enables the user to setup her billing info.After the user completes logging in and setting up the billing information, The Intel AppUp(SM) Center submits a purchase request to the AppUp Store Backend.
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 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 store 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 store 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 |
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 AppUpSM store
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 AppUpSM 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 AppUpSM 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 AppUpTM SDK 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 AppUpSM developer program 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://appdeveloper.intel.com 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 AppUpSM developer program 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 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 AppUpSM 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 AppUpSM 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 AppUpSM 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 AppUpSM 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 AppUpSM center. |
|
String_ADP_NOT_INITIALIZED |
The application did not initialize properly. |
|
String_ADP_TIMEOUT |
The Intel AppUpSM center response timed out. |
|
String_ADP_UPGRADE_ERRORMSG |
The application failed to send the upgrade request to the Intel AppUpSM 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 AppUpSM developer program 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 AppUpSM developer program 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 AppUpSM developer program portal, which requires that you enroll in the Intel AppUpSM developer program. 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 AppUpSM 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 AppUpSM developer program 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.\n\n
Hardware information\n\nPage size: %1!u!\n
Number of processors: %2!u!\n
Processor Architecture: %3!s!\n"),
siSysInfo.dwPageSize,
siSysInfo.dwNumberOfProcessors,
strProcessArchitecture);
pWnd->SetWindowTextW(strPlatformInfo);
}
