Intel AppUp Software Development Kit API Reference for .NET technology
SDK Version 1.5 Copyright © 2011 Intel Corporation. All Rights Reserved. Document Number: 324068-005US.
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
In-App Upgrade API
Defining and Calling Custom Crash Reports for C#
Defining and Calling Custom Crash Reports for Visual Basic
About this Document
This document is for developers using the Intel AppUpTM Software Development Kit 1.5 for .NET technology. The SDK (Software Development Kit) includes programming libraries, documentation, and sample code to help developers create, test, and submit .NET applications intended for distribution via the Intel AppUpSM center.
Intended Audience
This document is intended for experienced software developers who are developing applications for the Intel AppUpSM center, using one of the supported languages and graphical APIs. These can be new applications or existing applications being ported for the Intel AppUpSM center. The SDK supports the following languages and Microsoft Windows* graphical APIs:
C# for WPF (Windows Presentation Foundation) applications
C# for WinForms (Windows Forms) applications
Visual Basic for WPF applications
Visual Basic for WinForms applications
Note: This SDK supports products compiled targeting the .NET 3.5 Framework runtime. Developers creating applications that incorporate this SDK must compile and validate those applications in the .NET 3.5 Framework runtime.
Note: Not all SDK functions and capabilities are supported for each language/API combination.
Note: This SDK release supports development of Intel AppUpSM center applications only (not components).
Note: The use of SDK within applications for the Intel AppUpSM developer program is optional. However, all application developers for the Intel AppUpSM 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 for applications. 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 .NET SDK is provided in the Intel AppUpTM Software Development Kit Developer Guide for .NET technology document, which is shipped with the Intel AppUpTM Software Development Kit for .NET technology. The SDK is available on the Intel AppUpSM developer program portal.
Revision History
|
Document Number |
Revision Number |
Description |
Revision Date |
|
324068 |
001 |
Initial document release to support SDK for .NET technology V1.0 |
September 2010 |
|
|
002 |
Updated to support SDK for .NET technology V1.1: • Added End User Error Message Information. |
November 2010 |
|
|
003 |
Updated to support SDK for .NET technology V1.1.1: • Added In-Application Upgrade Call information. • Clarifications to existing content. |
February 2011 |
|
|
004 |
Updated to support SDK for .NET technology V1.1.2: • Updated to comprehend Intel AppUpTM Software Debugger 1.1.2. |
April 2011 |
|
|
005 |
Updated to support SDK for .NET technology V1.5: • Updated to comprehend Intel AppUpTM Software Debugger 1.5 |
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.
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 AppUpSM center applications to run on the client system.
Instrumentation Calls - Documents the SDK library calls to implement Instrumentation (metering) of applications.
In-App Upgrade API - Documents the SDK library In-App Upgrade API 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.
Configuration and Build Information
The following list provides basic configuration and build information needed to create applications:
This SDK supports products compiled targeting the .NET 3.5 Framework runtime. Developers creating applications that incorporate this SDK must compile and validate those applications in the .NET 3.5 Framework runtime. When working with Visual Studio* 2010, you must download and install the .NET Framework 3.5 separately from installing Visual Studio.
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 AppUpSM developer program .NET applications. When invoked, the application constructor performs the following operations: (1) it initializes the SDK library, (2) it authorizes the application via the Intel AppUpSM center, and (3) it executes a Begin Event (unless explicitly disabled). Exceptions are thrown if these operations fail. In addition, default Crash Reporting is enabled, unless custom Crash Reporting is implemented.
A short form and a long form of the call are supported. The short and long forms of the call have the following basic structure, respectively:
app = new AdpApplication(new AdpApplicationID(ApplicationID))
app = new AdpApplication(new AdpApplicationID (ApplicationID, beginEvent))
When the application constructor is invoked using the short form, default Instrumentation is enabled. The long form of the invocation allows default Instrumentation to be disabled via a Boolean value. This is usually done to implement custom Instrumentation.
C# Syntax (short form)
app = new AdpApplication(new namespace.AdpApplicationID(ApplicationID));
Parameters
app: name of the object (the application)
namespace: Intel.Adp (can be omitted if the namespace has been previously declared)
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 IDs discussion later.
C# Syntax (long form)
app = new AdpApplication(new namespace.AdpApplicationID(ApplicationID), beginEvent);
Parameters
app: name of the object (the application)
namespace: Intel.Adp (can be omitted if the namespace has been previously declared)
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 IDs discussion later.
beginEvent: Boolean type. true = enable default Instrumentation; false = disable default Instrumentation.
Visual Basic Syntax (short form)
Dim app As New AdpApplication(New namespace.AdpApplicationID(ApplicationID))
Parameters
app: name of the object (the application)
namespace: Intel.Adp (can be omitted if the namespace has been previously declared)
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 IDs discussion later.
Visual Basic Syntax (long form)
Dim app As New AdpApplication(New namespace.AdpApplicationID(ApplicationID), beginEvent)
Parameters
app: name of the object (the application)
namespace: Intel.Adp (can be omitted if the namespace has been previously declared)
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 IDs discussion later.
beginEvent: Boolean type. true = enable default Instrumentation; false = disable default Instrumentation.
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
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
C# Short Form Using Debug Application ID from SDK Library
The following example applies to both WPF and WinForms. The example uses an authorized Debug Application ID and a basic exception handler. The Intel.Adp namespace has been previously declared.
/// <ADP>
try
{
AdpApplication app = new AdpApplication(new AdpApplicationID(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
}
catch (AdpException e)
{
if ( e is AdpErrorException)
{
// TO DO: add your logic to handle the errors during initialization
MessageBox.Show(e.Message, "Error");
System.Environment.Exit(1);
}
else if ( e is AdpWarningException)
{
// TO DO: add your logic to handle the warnings
MessageBox.Show(e.Message, "Warning");
}
}
/// </ADP>
C# Long Form Using Production Application ID
The following example applies to both WPF and WinForms. The example uses a Production Application ID. The exception handler is assumed and the Intel.Adp namespace has been previously declared.
/// <ADP>
try
{
AdpApplication app = new AdpApplication(new AdpApplicationID(0x12341234, 0x56785678, 0x12341234, 0x56785678));
}
/// Exception handler goes here
/// </ADP>
C# Long Form Using Debug Application ID
The following example applies to both WPF and WinForms. Default Instrumentation is disabled. The example uses a Production Application ID. The exception handler is assumed and the Intel.Adp namespace has been previously declared.
/// <ADP>
try
{
AdpApplication app = new AdpApplication(new AdpApplicationID(0x11111111, 0x11111111, 0x11111111, 0x11111111), false);
/// Note: replace (0x11111111, 0x11111111, 0x11111111, 0x11111111) 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
}
/// Exception handler goes here
/// </ADP>
Visual Basic Short Form Using Debug Application ID from SDK Library
The following example applies to both WPF and WinForms. The example uses an authorized Debug Application ID and a basic exception handler. The Intel.Adp namespace has been previously declared.
Try
Dim app As New AdpApplication(New AdpApplicationId AdpConstants.ADP_DEBUG_APPLICATIONID))
application ID
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
Catch ex As AdpException
If TypeOf ex Is AdpErrorException Then
' TO DO: add your logic to handle the errors during initialization
MsgBox(ex.Message)
System.Environment.Exit(1)
ElseIf TypeOf ex Is AdpWarningException Then
' TO DO: add your logic to handle the warnings
MsgBox(ex.Message)
End If
End Try
Visual Basic Long Form Using Production Application ID
The following example applies to both WPF and WinForms. The example uses a Production Application ID. The exception handler is assumed and the Intel.Adp namespace has been previously declared.
Try
Dim app As New AdpApplication(New AdpApplicationId(0x12341234, 0x56785678, 0x12341234, 0x56785678))
Exception handler goes here
End Try
Visual Basic Long Form Using Debug ID
The following example applies to both WPF and WinForms. Default Instrumentation is disabled. The exception handler is assumed and the Intel.Adp namespace has been previously declared.
Try
Dim app As New AdpApplication(New AdpApplicationId(&H11111111, &H11111111, &H11111111, &H11111111), false)
' Note: replace "&H11111111, &H11111111, &H11111111, &H11111111" 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
Exception handler goes here
End Try
Shutdown Behavior
On application or process exit, the SDK library releases the object. Releasing the object includes executing an End Event and closing the SDK library.
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.
The short form of the Application Constructor call enables an automatic Begin Event parameter. When the application constructor runs, it automatically triggers a Begin Event. When the application or process exits, an End Event is automatically triggered.
The long form of the Application Constructor call can be used to disable the automatic Begin Event and End Event triggers to implement explicit Instrumentation if desired.
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 explicitly including Begin Event in your application, you must define the object as a member variable of the class where the BeginEvent call will be inserted. The C# method is shown below:
public partial class AdpHelloWorldWindow : Window
{
Intel.Adp.Application app;
public AdpHelloWorldWindow()
{
InitializeComponent();
/// <ADP>
try
{
AdpApplication app = new AdpApplication(new AdpApplicationID(AdpConstants.ADP_DEBUG_APPLICATIONID), false);
}
/// catches for warnings and exceptions
/// </ADP>
}
}
Next, disable the automatic Begin Event that the application constructor runs by default. This is accomplished by using a longer form of the Application Constructor call with a Boolean false as a parameter after the GUID, as shown above.
Then you can insert the BeginEvent call at the point where you wish to trigger the event.
C# Syntax
app.BeginEvent();
Paramters
app: name of the object (the application)
Visual Basic Syntax
app.BeginEvent()
Parameters
app: name of the object (the application)
If the BeginEvent is successful, then a Begin Event message is triggered. Otherwise an exception is thrown. The following exceptions 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 Examples
C# Code Example
The following example applies to both WPF and WinForms. The exception handler is assumed.
try
{
app.BeginEvent();
}
/// TO DO add your error handling here
Visual Basic Code Example
The following example applies to both WPF and WinForms. The exception handler is assumed.
Try
app.BeginEvent()
' TO DO add your error handling here
End Try
End Event Call
End Events must be preceded by Begin Events, whether those Begin Events are automatic (i.e., run by the application constructor) or explicit. Before explicitly 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. (See the earlier example in the BeginEvent call discussion.)
Then insert the EndEvent call at the point where you wish to trigger the event.
C# Syntax
app.EndEvent();
Parameters
app: name of the object (the application)
Visual Basic Syntax
app.EndEvent()
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 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 Examples
C# Code Example
The following example applies to both WPF and WinForms. The exception handler is assumed.
try
{
app.EndEvent();
}
/// TO DO add your error handling here
Visual Basic Code Example
The following example applies to both WPF and WinForms. The exception handler is assumed.
Try
app.EndEvent()
' TO DO add your error handling here
End Try
In-App Upgrade API
The Intel AppUpTM SDK library provides an API to support upgrading to one designated version of an application. Typical usage of this In-App 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-App 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.
C# Syntax
app.Upgrade(new AdpApplicationId(TargetApplicationId));
Parameters
app: name of the application object
TargetApplicationId: a Production Application GUID (see Target Application ID discussion later).
Visual Basic Syntax
app.Upgrade(New AdpApplicationId(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-App 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 Examples
C# Example
The following example shows the In-App Upgrade call in C#, using a Production Application ID and basic error and warning exception handlers.
try
{
app.Upgrade(new AdpApplicationId(0x22222222,0x33333333,0x44444444,0x55555555));
}
catch (AdpException ex)
{
if (ex is AdpErrorException)
{
// TO DO: add your logic to handle the errors at run time
MessageBox.Show(ex.Message, "Fatal Error");
System.Environment.Exit(1);
}
else if (ex is AdpWarningException)
{
// TO DO: add your logic to handle the warnings
MessageBox.Show(ex.Message, "Warning");
}
}
Visual Basic Example
The following example shows the In-App Upgrade call in Visual Basic, using a Production Application ID and basic error and warning exception handlers.
Private Sub ButtonUpgrade_Click(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs) Handles ButtonUpgrade.Click
Try
_app.Upgrade(New AdpApplicationId(&H22222222, &H33333333, &H44444444, &H55555555))
' Note: replace "0x22222222,0x33333333,0x44444444,0x55555555" with the actual target application ID
' once you obtain it from Intel AppUp(SM) Developer Program web portal
Catch ex As AdpException
If TypeOf ex Is AdpErrorException Then
' TO DO: add your logic to handle the errors at run time
MsgBox(ex.Message)
System.Environment.Exit(1)
ElseIf TypeOf ex Is AdpWarningException Then
' TO DO: add your logic to handle the warnings
MsgBox(ex.Message)
End If
End Try
End Sub
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 .NET technology 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 |
The behavior of DefaultCrashReport is to populate the Developer fields with the following information:
ModuleName - The source code module name where the exception occurred.
LineNumber - The source code line number where the exception occurred.
Category - The exception type code.
Message - The text message string for the exception.
ErrorData - Corestack data at the time the exception occurred.
Custom crash reports derived from DefaultCrashReport follow the same behavior unless fields are explicitly overridden by the Developer.
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.
Defining and Calling Custom Crash Reports for C#
The following example shows the framework to set and define a custom crash report for C#. Note that the crash report is set immediately after the Application Constructor call. An Application Debug ID is used for this example.
try
{
app = new AdpApplication(new AdpApplicationId(0x11111111, 0x11111111, 0x11111111, 0x11111111), false);
/// Note: replace "0x11111111, 0x11111111, 0x11111111, 0x11111111" with the actual application ID
/// once you obtain it from Intel AppUp(SM) Developer Program web portal
// Set my own crash report
app.SetCrashReport(new MyCrashReport());
}
public class MyCrashReport : DefaultCrashReport
{
/// <summary>
/// This method is provided to populate the AbstractCrashReport::_message member variable
/// </summary>
public override void PopulateMessage()
{
this._message = this.UnhandledException.Message;
}
/// <summary>
/// This method is provided to populate the AbstractCrashReport::_category member variable.
/// </summary>
public override void PopulateCategory()
{
this._category = this.UnhandledException.GetType().ToString();
}
/// <summary>
/// This method is provided to populate the AbstractCrashReport::_errorData member variable.
/// </summary>
public override void PopulateErrorData()
{
if (this._ex.StackTrace.Length > AdpConstants.ADP_MAX_ERR_DATASIZE)
this._errorData = this.UnhandledException.StackTrace.Substring(0, AdpConstants.ADP_MAX_ERR_DATASIZE - 1);
else
this._errorData = this.UnhandledException.StackTrace;
}
/// <summary>
/// This method is provided to populate the AbstractCrashReport::_customField member variable.
/// </summary>
public override void PopulateCrashReportFields()
{
if (this._customField != null)
this._customField.Clear();
ADP_CrashReportField x;
x.name = "MyReportFieldName";
x.value = "MyReportFieldValue";
this._customField.Add(x);
}
}
Defining and Calling Custom Crash Reports for Visual Basic
The following example shows the framework to set and define a custom crash report for Visual Basic. Note that the crash report is set immediately after the Application Constructor call. An Application Debug ID is used for this example.
Try
app = New AdpApplication(New AdpApplicationId(&H11111111, &H11111111, &H11111111, &H11111111), False)
' Note: replace "&H11111111, &H11111111, &H11111111, &H11111111" 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
app.SetCrashReport(New MyCrashReport())
Class MyCrashReport
Inherits DefaultCrashReport
''' <summary>
''' This method is provided to populate the AbstractCrashReport::_message member variable
''' </summary>
''' <remarks></remarks>
Public Overrides Sub PopulateMessage()
Me._message = Me.UnhandledException.Message
End Sub
End Class
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
C# Code Example
The following example shows the C# catch sequence following an Application Constructor call. This sequence includes catches for the error and warning exception classes.
/// Application constructor call goes here
catch (AdpException ex)
{
if (ex is AdpErrorException)
{
if (ex is InitializationException)
{
// TO DO: add your logic to handle the errors during initialization
MessageBox.Show(ex.Message, "Initialization Error");
System.Environment.Exit(1);
}
else if (ex is UnauthorizedException)
{
// TO DO: add your logic to handle the errors during authorization
MessageBox.Show(ex.Message, "Authorization Error");
System.Environment.Exit(1);
}
if (ex is AdpRunTimeException)
{
// TO DO: add your logic to handle the errors during runtime
MessageBox.Show(ex.Message, "Initialization Error");
System.Environment.Exit(1);
}
}
else if (ex is AdpWarningException)
{
// TO DO: add your logic to handle the warnings
MessageBox.Show(ex.Message, "Warning");
}
}
Visual Basic Code Example
The following example shows the Visual Basic catch sequence following an Application Constructor call. This sequence includes catches for the error and warning exception classes.
Application constructor call goes here
Catch ex As AdpException
If TypeOf ex Is AdpErrorException Then
If TypeOf ex Is InitializationException Then
' TO DO: Initialization error message and logic
MsgBox(ex.Message)
System.Environment.Exit(1)
If TypeOf ex Is UnauthorizedException Then
' TO DO: Initialization error message and logic
MsgBox(ex.Message)
System.Environment.Exit(1)
If TypeOf ex Is AdpRuntimeException Then
' TO DO: Runtime error message and logic
MsgBox(ex.Message)
System.Environment.Exit(1)
End If
ElseIf TypeOf ex Is AdpWarningException Then
' TO DO: Warning message and logic
MsgBox(ex.Message)
End If
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 the .Code property added to the variable name in the message declaration. (In the examples shown here, e.Code for C# or ex.Code for Visual Basic.)
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. |
