SDKVersion 0.8 Beta. Copyright(C) 2011 Intel Corporation. All Rights Reserved. Document Number: 324700-001US.

Contents

• About this Document
• Intended Audience
• Using this API Reference
• Conventions and Symbols
• Related Information
• Application Reference Information
• Configuration and Build Information
• Application Class Structure
• Application Constructor Call
• Authorization Code Examples
• Cleanup Code
• Instrumentation
• Begin Event Call
• End Event Call
• Crash Reporting
• Crash Reporting Class Structure
• AbstractCrashReport Details
• DefaultCrashReport Details
• Exceptions
• InitializationException
• UnauthorizedException
• AdpRuntimeException
• AdpWarningException
• Code Example for Exceptions
• Return/Error Codes
• End User Error Messages
• Revision History
• Disclaimer and Legal Information

About this Page

This page is for developers using the Intel AppUp(TM) Software Development Kit 0.8 Beta for MeeGo C/C++ Developers for Windows to develop C++ applications within a Microsoft* Windows* development environment and targeted for a MeeGo* runtime environment. The SDK (Software Development Kit) includes programming libraries, documentation, and sample code to help developers create, test, and submit C++ applications intended for distribution via the Intel AppUp(SM) center.

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

Intended Audience

This page is intended for experienced software developers who are developing applications for the Intel AppUp center. These can be new applications or existing ones being ported forthe Intel AppUp center. This SDK supports development of C++ applications for MeeGo 1.1 with MeeGo 1.1 SDK for Windows. This SDK supports development in a Microsoft Windows 7* or Windows XP* 32-bit OS environment.

Both the MeeGo 1.1 SDK and the Intel AppUp SDK 0.8 Beta for MeeGo C/C++ Developers on Windows need to be installed.

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

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.

Conventions and Symbols

The following table shows the conventions used in this document.

Related Information

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

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.
• Application Class Structure — Defines the class structure for applications.
• 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.
• 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.

Configuration and Build Information

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

• Verify that the MeeGo 1.1 SDK is installed.
• Verify that the Qt Creator project has statically linked the application to the SDK Library. The following lines must appear in the Qt Creator application project (.pro) files:
  

  	LIBS += -lxml2\
  			-lpthread
  	LIBS += "$$(IADP_SDK_DIR_MEEGO)Cpp\lib\libadpruntime.a"\
  			"$$(IADP_SDK_DIR_MEEGO)Cpp\lib\libadpcore.a"\
  			"$$(IADP_SDK_DIR_MEEGO)Cpp\lib\libxerces-c.a"\
  			"$$(IADP_SDK_DIR_MEEGO)Cpp\lib\libxml-security-c.a"\
  			"$$(IADP_SDK_DIR_MEEGO)Cpp\lib\libcrypto.a"
  	

• IADP_SDK_DIR_MEEGO is the installation path of the SDK. The default path is Program Files/Intel/IntelAppUpSDKMeeGo/Cpp/lib/.

Application Class Structure

The Application class is the root of the SDK Framework’s class hierarchy, which is based on an internal SDK library Product class. This relationship is shown in the figure below. (A future Component class may also be based on the same Product class. Components are not currently supported and will not be discussed further in this version of the document.)

Application Constructor Call

The Application Constructor call is the only required call for Intel AppUp 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 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)

Application IDs

The Application ID is a unique identifier for Intel AppUp 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 to upload your application to the Intel AppUp Developer Program portal.

Debug Application ID — During development, the Application Debug ID allows testing with the Intel AppUp(TM) 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 ones.
• 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 zeros.

Production Application ID — Production IDs are obtained from the Intel AppUp Developer Program portal, which requires that you enroll in the Intel AppUp 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 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) {
			qDebug("Caught exception in application. Exception code:
				%ld/n", e.code());
		}
	}
	/// </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>

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)

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
			qDebug("Caught exception in application with Exception code:
				%ld\n", e.code());
		}

		/// 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();
}

myApp: name of the object (the application)

If the EndEventcall 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)

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
		qDebug("Caught EndEvent exception in application with Exception code:
			%ld\n", e.code());
	}
	catch (AdpWarningException& e) {
			// Your code to handle EndEvent warnings
		qDebug("Caught EndEvent warning in application with Exception code:
			%ld\n", e.code());
	}
	// Application code goes here

Crash Reporting

The Intel AppUp 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 AppUp 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++ and MeeGo provides more information on My Dashboard and on 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 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 AppUp 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.

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

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

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

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

	com::intel::adp::Application *pBasicSampleApp = NULL;
		try{
			// NOTE: Most testing is done with the ADP_DEBUG_APPLICATIONID GUID, which
			// is the Authorized Application ID. When validation/testing is completed,
				// replace ADP_DEBUG_APPLICATIONID with Production Application ID
			pBasicSampleApp = new Application(ADP_DEBUG_APPLICATIONID);
			qDebug("Application Authorized to run.\n");
		}
	catch (com::intel::adp::InitializationException& e) {
		/* Catches error exceptions thrown while the SDK application constructor
		* attempts to initialize the SDK library code.
		* It can also occur if a Component is
		* instantiated before the Application object.
		* Inherits the AdpErrorException Class
		*/
		qDebug("Caught Initialization exception in application with exception
			code: %ld\n", e.code());
	}
	catch (com::intel::adp::UnauthorizedException& e) {
		/*This exception is thrown if an application or component is not
		* authorized or is expired. Exceptions thrown while the SDK library
		* code attempts to authorize the application and is unauthorized.
		* Inherits the AdpErrorException Class
		*/
		qDebug("Caught Unauthorized exception in application with exception
			code: %ld\n", e.code());
	}
	catch (com::intel::adp::AdpRuntimeException& e) {
		/* This exception is a catch all for all errors that are not covered
		* by InitializationException or UnauthorizedException. Catches
		* general runtime error exceptions while executing SDK library code.
		* Inherits the AdpErrorException Class
		*/
		qDebug("Caught Runtime exception in application with exception code:
			%ld\n", e.code());
	}