This document is for developers using the Intel AppUp^TM Software Development Kit 1.1.1 for Java software to develop applications and components for a Java runtime environment. The SDK (Software Development Kit) includes programming libraries, documentation, and sample code to help developers create, test, and submit Java applications and components intended for distribution via the Intel AppUp^SM center.

Intended Audience

This document is intended for experienced software developers who are developing applications and components for the Intel AppUp^SM center. These can be new applications/components or existing ones being ported for the Intel AppUp^SM center. The SDK supports development of Java* application/components for a Java SE 1.6 (or later) runtime environment.

Note: The use of SDK within applications for the Intel AppUpSM developer program is optional while it is still mandatory for components to use the SDK. However, all application developers for the Intel AppUpSM developer program are encouraged to read the document to fully understand the advantages that the SDK provides and directions on using it. The development flows and samples assume SDK integration.

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 and Exceptions for applications. Code examples are provided, as appropriate.
Component Reference Information, documents the SDK API Calls and Exceptions for components. Code examples are provided, as appropriate.

Conventions and Symbols

The following table shows the conventions used in this document.

Conventions and Symbols 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.
Notes, cautions, etc.	Note: Indicates an important comment or side topic for the user.

Related Information

Getting Started information for the Java SDK is provided in the Intel AppUp^TM Software Development Kit Developer Guide for Java* software document, which is shipped with the Intel AppUp^TM Software Devleopment Kit for Java* software. The SDK is available on the Intel AppUp^SM Developer Program portal.

Application Reference Information

This section documents the SDK API Calls and Exceptions. The following subsections are provided:

Class Structure — Defines the class structure for the SDK library.
Application Constructor Call — Documents the SDK library Application Constructor call, which is required to authorize Intel AppUp^SM center applications to run on the client system.
Application Shutdown Call — Documents the SDK library Application Shutdown call.
Instrumentation Calls — Documents the SDK library calls to implement Instrumentation (metering) of applications.
In-Application Upgrade Call — Documents the SDK library In-Application Upgrade call that determines if an application is authorized for an upgrade.
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.

Class Structure

The Application class is the root of the Java Framework’s class hierarchy for applications. The Component class is the root of the Java 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. Extending the Application class is the recommended approach for new applications. Only one instance of the Application class can be created.

Application Constructor Call

The Application Constructor call is the only required call for Intel AppUp^SM Developer Program Java 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^SM center. Exceptions are thrown if these operations fail. In addition, default Crash Reporting is enabled, unless custom Crash Reporting is implemented.

Syntax

Application app = new Application(namespace.ApplicationId);

Parameters

app: 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)

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.

See the Application ID discussion later.

Error Codes (ADP_RET_CODE data type)

Value	Meaning
ADP_FAILURE	Operation was unsuccessful. It can also indicate that more than one instantiation of the application was attempted.
ADP_NOT_AVAILABLE	Operation failed because the SDK library was not available. This can occur if the Intel AppUp^SM center software is not installed properly.
ADP_NOT_INITIALIZED	Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.
ADP_INCOMPATIBLE_VERSION	Operation failed because the API version of the application is not supported by the current Intel AppUp^SM center software.
ADP_NOT_AUTHORIZED	The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.
ADP_AUTHORIZATION_EXPIRED	The application’s license has expired. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.
ADP_TIMEOUT	Operation failed because the connection between the SDK and the Intel AppUp^SM center client swoftware timed out.

Application IDs

The Application ID is a unique identifier for Intel AppUp^SM 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 AppUp^SM 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^TM Software Debugger to get an ADP_AUTHORIZED response back. This allows most of the application to be tested and debugged. The value of this Debug ID is all one's.
ADP_EXPIRED_APPLICATIONID: Used with the Intel AppUp^TM 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 AppUp^SM Developer Program portal, which requires that you enroll in the Intel AppUp^SM Developer Program. The Production ID is a 128-bit number organized as four integers in hex format.

Notes

A sensible approach to handling an ADP_TIMEOUT error during the first authorization attempt is to attempt authorization again.
Multiple Application Constructor calls can be made, but the Application ID from the first call is the only one used in the application (e.g., in a crash report).

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.

import com.intel.adp*;

try {

Application app = new Application(AdpConstants.ADP_DEBUG_APPLICATIONID);

}

catch( AdpErrorException e) {

e.printStackTrace();

}

Using Production Application ID

The following example uses a Production Application ID and a basic exception handler.

import com.intel.adp*;

try {

Application app = new ApplicationId(0x12341234, 0x56785678,

0x12341234, 0x56785678) ;

}

catch( AdpErrorException e) {

e.printStackTrace();

}

Application Shutdown Call

The Application Shutdown call releases the object. Releasing the object closes the SDK library. This call must be located in the shutdown code for the application.

Syntax

app.dispose();

Parameters

app: name of the application object

No exceptions are thrown and no error/return codes are provided.

Code Example

The following example shows the Application Shutdown call.

import com.intel.adp.*;

app.dispose();

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^SM center for the application.
Application End Event – Triggers sending an End Event message to the Intel AppUp^SM 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

Before including Begin Event in your application, you must first define the object as a member variable of the class where the beginEvent call will be inserted.

Then you can insert the beginEvent call at the point where you wish to trigger the event. It is recommended that you included it immediately after the Application Constructor call. This causes the Begin Event message to be triggered when the application is first authorized and allows the beginEvent call to share the same exception handler as the Application Constructor call.

Syntax

try {

app.beginEvent();

}

Parameters

app: 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	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.

Notes

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

Code Example

The following example shows the beginEvent call included immediately after the Application Constructor call. (The call can be made any place in the application after the Application Constructor call.) An Application Debug ID and a basic exception handler are used.

import com.intel.adp.*;

Application app = null;

try {

app = new Application(AdpConstants.ADP_DEBUG_APPLICATIONID);

app.beginEvent();

}

catch (AdpRuntimeException e) {

System.out.println("Exception occured - " + e.getMessage());

}

End Event Call

End Events must be preceded by Begin Events. Before explicitly including End Event in your application, you must first define the object as a member variable of the class where the endEvent call will be inserted. (This should be done already when implementing Begin Event.) Then insert the endEvent call at the point where you wish to trigger the event.

Syntax

try {

appndEvent();.e

}

Parameters

app: 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 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^SM center software.

Code Example

The following example shows the endEvent call. A warning exception handler and an error exception handler are used.

import com.intel.adp.*;

try {

app.endEvent();

}

catch(AdpWarningException e) {

System.out.println("Exception occured - " + e.getMessage());

}

catch(AdpRuntimeException e) {

System.out.println("Exception occured - " + e.getMessage());

}

In-Application Upgrade Call

The Intel AppUp^TM 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(new ApplicationId(TargetApplicationId));

Parameters

app: name of the application object

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

If the Upgrade Authorization is successful, then the application can continue. Otherwise an exception is thrown, as follows:

AdpRuntimeException – Failure in the general runtime environment.

Error Codes (ADP_RET_CODE data type)

Value	Meaning
ADP_FAILURE	Operation was unsuccessful. It can also indicate that more than one instantiation of the application was attempted.
ADP_NOT_INITIALIZED	Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.
ADP_NOT_AUTHORIZED	The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.

Target Application ID

In general, the Application ID is a unique identifier for Intel AppUp^SM Developer Program applications. The In-Application Upgrade call uses a Production Application ID to represent the target application to upgrade to. 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 AppUp™ developer 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 basic error and warning exception handlers.

try {

app.upgrade(new ApplicationId(0x11111111,0x22222222,0x33333333,0x44444444));

}

catch (AdpErrorException e) {

System.out.println("Exception occured - " + e.getMessage());

}

catch (AdpWarningException e) {

System.out.println("Exception occured - " + e.getMessage());

}

-->

Crash Reporting

The Intel AppUp^TM 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^SM 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 Java 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 AppUp^SM 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 Java 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.

AbstractCrashReport Details

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;

If you wish to provide customized unhandled crash reporting you need to override the pure abstract methods in AbstractCrashReport, populating these variables.

The AbstractCrashReport class offers the following virtual overrides

protected abstract void populateModuleName()

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

protected abstract void populateLineNumber()

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

protected abstract void populateMessage

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

protected abstract void populateCategory()

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

protected abstract void populateErrorData()

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

protected abstract void populateCrashReportFields()

This method is provided to populate the AbstractCrashReport:: crashReportFields member variables.

Customizing DefaultCrashReport

The following example shows the framework to define and call a custom crash report for Java, using MyExceptionHandler to extend DefaultCrashReport. Implementation of custom Crash Reporting automatically disables default Crash Reporting.

import java.lang.thread.*;

import com.intel.adp.*;

public class CustomizeCrashReportSample {

/**

* @param args

public static void main(String[] args) {

Application app = null;

try {

app = new Application(AdpConstants.ADP_DEBUG_APPLICATIONID);

app.setCrashReport(new MyExceptionHandler());

}

catch ( AdpException e) {

e.printStackTrace();

System.exit(1);

}

if(app != null) {

throw new Exception("Something bad happened! But this is expected.");

}

System.exit(0);

}

class MyExceptionHandler extends DefaultCrashReport{

@Override

protected void populateCategory() {

// TODO Auto-generated method stub

this.errorCategory = "My Error Category";

}

@Override

protected void populateCrashReportFields() {

this.crashReportFields = new AdpCrashReportField[1];

this.crashReportFields[0] = new AdpCrashReportField("Sub_Category",

"Trapped Error");

}

@Override

protected void populateErrorData() {

// TODO Auto-generated method stub

super.populateErrorData();

}

@Override

protected void populateLineNumber() {

// TODO Auto-generated method stub

super.populateLineNumber();

}

@Override

protected void populateMessage() {

// TODO Auto-generated method stub

this.errorMessage = "User of illegal method";

}

@Override

protected void populateModuleName() {

// TODO Auto-generated method stub

super.populateModuleName();

}

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 described 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 Java code sample below includes a catch for each of the SDK library error exceptions. See the endEvent call earlier for an example of a catch for the warning exception class.

try {

Application app = new Application(AdpConstants.ADP_DEBUG_APPLICATIONID);

}

catch (InitializationException e) {

// TODO Add your logic to handle initialization errors

e.printStackTrace();

}

catch (UnauthorizedException e) {

// TODO Add your logic to handle authorization errors

e.printStackTrace();

}

catch (AdpRuntimeException e) {

// TODO Add your logic to handle runtime errors

e.printStackTrace();

}

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 including e.Code in the message declaration.

API Call Return/Error Codes

Value	Meaning
ADP_SUCCESS	Operation was successful.
ADP_FAILURE	Operation was unsuccessful.
ADP_NOT_AVAILABLE	Operation failed because the SDK library was not available. This can occur if the Intel AppUp^SM center software is not installed properly.
ADP_NOT_INITIALIZED	Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.
ADP_INCOMPATIBLE_VERSION	Operation failed because the API version of the application is not supported by the current Intel AppUp^SM center software.
ADP_AUTHORIZED	The application is authorized to run.
ADP_NOT_AUTHORIZED	The application is not authorized to run. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.
ADP_AUTHORIZATION_EXPIRED	The application’s license has expired. Applications can choose how to respond, such as preventing an application from running, allowing the application to run for a grace period so the user can obtain a license, allowing the application to run with limited functionality, etc.
ADP_NO_APP_BEGIN_EVENT	Operation failed because an End Event has been attempted with no prior Begin Event. A Begin Event call must precede an End Event call in the application.
ADP_TIMEOUT	Operation failed because the connection between the SDK library and the Intel AppUp^SM center client software timed out.

End User Error Messages

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

End User Error Messages

Message ID	Message Text
String_ADP_AUTHORIZATION_EXPIRED	The license for this application has expired.
String_ADP_BEGINEVENT_ERROMSG	The application experienced an error while starting a usage record.
String_ADP_ENDEVENT_ERRORMSG	The application experienced an error while ending a usage record.
String_ADP_FAILURE	The application experienced a critical error.
String_ADP_INCOMPATIBLE_VERSION	The current Intel AppUp^SM center software does not support this version of the application.
String_ADP_NO_APP_BEGIN_EVENT	The application did not complete a start of usage record.
String_ADP_NOT_AUTHORIZED	The application is not authorized to run under this account on this device.
String_ADP_NOT_AVAILABLE	The application cannot connect to the Intel AppUp^SM center.
String_ADP_NOT_INITIALIZED	The application did not initialize properly.
String_ADP_TIMEOUT	The Intel AppUp^SM center response timed out.
String_ADP_UPGRADE_ERRORMSG	The application failed to send the upgrade request to the Intel AppUp^SM 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 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.

Only one instance of each Component may exist within an Application.
The Component is automatically deleted when the Application class is deleted.
Exception handling for components is the same as for applications.
Instrumentation (Begin Events and End Events) is not supported at the component level.
Crash Reporting is not supported at the component level.

Component IDs

The Component ID is a unique identifier for Intel AppUp^SM 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 — 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 — 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.

Component Call in Applications

The Component Constructor call determines if an Intel AppUp^SM Developer Program component is authorized to run on a client system. When invoked, the component constructor authorizes the application via the Application Services of the Intel AppUpSM center client software. Exceptions are thrown if the operation fails. The Component Constructor call must be placed after the Application Constructor call in the application.

Syntax

comp comp = new comp();

Parameters

comp: name of the component object

If the Component Constructor is successful, then a Component object is run. 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 component.
AdpRuntimeException – Failure in the general runtime environment.

Error Codes (ADP_RET_CODE data type)

Value	Meaning
ADP_FAILURE	Operation was unsuccessful.
ADP_NOT_AVAILABLE	Operation failed because the SDK library was not available. This can occur if the Intel AppUp^SM center software is not installed properly.
ADP_NOT_INITIALIZED	Operation failed because the SDK library is not initialized. Any API call made prior to initialization causes this code to be generated.
ADP_INCOMPATIBLE_VERSION	Operation failed because the API version of the application is not supported by the current Intel AppUp^SM center software.
ADP_NOT_AUTHORIZED	The component is not authorized to run. Components can choose how to respond, such as preventing an component from running, allowing the component to run for a grace period so the user can obtain a license, allowing the component to run with limited functionality, etc.
ADP_AUTHORIZATION_EXPIRED	The component’s license has expired. Components can choose how to respond, such as preventing an component from running, allowing the component to run for a grace period so the user can obtain a license, allowing the component to run with limited functionality, etc.
ADP_TIMEOUT	Operation failed because the connection between the SDK library and the Intel AppUp^SM center client software timed out.

Component Construction

Components use the superclass super call to create the component and determine if an Intel AppUp^SM Developer Program component is authorized to run on a client system. When invoked, the component constructor authorizes itself via the Intel AppUp^SM center Application Services on the Consumer Client. Exceptions are thrown if the operation fails.

Syntax

public comp() throws UnauthorizedException,

InitializationException, AdpRuntimeException {

super(ComponentID);

}

Parameters

comp: name of the component object

ComponentID: A Component GUID (see the Component IDs discussion ealier in this section).

If the Component Construction is successful, then the Component runs. 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 component.
AdpRuntimeException – Failure in the general runtime environment.

Notes

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

Code Examples

Using Debug IDs From SDK Library

The following example shows the Component Constructor call inside an application. The example uses a basic exception handler. SampleComponent is a component that displays a greeting message to the screen, then returns. The component is created using the superclass Constructor super. The code for the component itself is shown below the Component Constructor call and uses a Debug Component ID.

// Application constructing the component

public void actionPerformed(ActionEvent e){

// TODO Auto-generated method stub

try {

SampleComponent comp = new SampleComponent();

showInInfolist(comp.greeting());

} catch(AdpException e1){

showInInfolist(e1.getMessage());

}

// The component

class SampleComponent extends Component{

public SampleComponent() throws UnauthorizedException,

InitializationException, AdpRuntimeException {

super(ComponentId.DEBUG_ID);

// TODO Auto-generated constructor stub

}

String greeting(){

return "Greeting from " + this.getClass().getName();

}

Using Production IDs

The following example is an excerpt of the previous component example, but with a Component Production ID.

public SampleComponent() throws UnauthorizedException,

InitializationException, AdpRuntimeException {

super(ComponentId.(0x55555555,0x66666666,0x77777777,0x88888888));

// TODO Auto-generated constructor stub

}

Revision History

Document Number	Revision Number	Description	Revision Date
324269	001	Initial document release to support Java SDK V1.1	December 2010
	002	Initial document release to support Java SDK V1.1.1: • In-Application Upgrade Call information added. • Clarifications to existing content.	February 2011
	003	Updated In-Application Upgrade Call information.	May 2011

Disclaimer and 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.

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

Average:

Average: 4.7 (3 votes)

Tags:

Intel AppUpSM developer program

Intel AppUp Software Development Kit API Reference for Java software

About this Document

Intended Audience

Using this API Reference

Conventions and Symbols

Related Information

Application Reference Information

Class Structure

Application Constructor Call

Authorization Code Examples

Application Shutdown Call

Parameters

Code Example

Instrumentation

Begin Event Call

Code Example

End Event Call

Code Example

In-Application Upgrade Call

Parameters

Code Example

Crash Reporting

Crash Reporting Class Structure

AbstractCrashReport

DefaultCrashReport

AbstractCrashReport Details

protected abstract void populateModuleName()

protected abstract void populateLineNumber()

protected abstract void populateMessage

protected abstract void populateCategory()

protected abstract void populateErrorData()

protected abstract void populateCrashReportFields()

Customizing DefaultCrashReport

Exceptions

Error Exception Classes

Warning Exception Class

InitializationException

UnauthorizedException

AdpRuntimeException

AdpWarningException

Code Examples for Exceptions

Return/Error Codes

End User Error Messages

Component Reference Information

Component Guidelines

Component IDs

Component Call in Applications

Parameters

Component Construction

Parameters

Code Examples

Using Debug IDs From SDK Library

Using Production IDs

KEY ACTIONS

DEVELOPMENT PLATFORMS

HOME

DEVELOPMENT

SDK & TOOLS

DOCUMENTATION

OPPORTUNITIES

COMMUNITY

SUPPORT

FOLLOW US ON

Intel AppUp^SM developer program