com.nokia.mid.payment
Class IAPClientPaymentManager

java.lang.Object
  com.nokia.mid.payment.IAPClientPaymentManager

public final class IAPClientPaymentManager
extends java.lang.Object

This is the main class for initiating and managing the purchase process for the purchaseable items in an application. Its methods are asynchronous with responses received from the underlying implementation callbacks All API methods except getProductData() will initiate the user authentication by Single-Sign On (SSO).The IAPClientPaymentManager class handles a single API function call at a time. If a second request is made while response is pending from a previous function call, a failure value is returned indicating that this request shall not be processed and no callback can be expected for this request.

 sample code snippet
 package sample;

 import javax.microedition.midlet.*;
 import javax.microedition.lcdui.*;
 import com.nokia.mid.payment.*;
 import java.io.*;

 public class SampleMIDlet extends MIDlet implements CommandListener, IAPClientPaymentListener
 {
     private Display display;     // The display for this MIDlet
     private IAPClientPaymentManager manager;  //Singleton instance of IAPClientPaymentManager() class

     public SampleMIDlet()
     {
         display = Display.getDisplay(this);
     }

     public void startApp()
     {
         int status = 0;

         try {
             // set IAPClientPaymentListener
             manager = IAPClientPaymentManager.getIAPClientPaymentManager();
             manager.setIAPClientPaymentListener(this);

             // request metadata for product "game_level_3"
             status = manager.getProductData("123456");
             if (status != IAPClientPaymentManager.SUCCESS) {
                 // Do not expect a productDataReceived() callback with the requested metadata, handle the fail case
             }
         } catch (IAPClientPaymentException e) {
             // handle IAPClientPaymentException from getIAPClientPaymentManager()
         }

         status = manager.purchaseProduct("123456", IAPClientPaymentManager.FORCED_AUTOMATIC_RESTORATION);

         if(status != IAPClientPaymentManager.SUCCESS)
         {
             // Do not expect a purchaseCompleted() asynchronous callback, handle the fail case
         }

         // restore product "game_level_5"
         status = manager.restoreProduct("112233", IAPClientPaymentManager.ONLY_IN_SILENT_AUTHENTICATION);
         if(status != IAPClientPaymentManager.SUCCESS)
         {
             // Do not expect a restoreCompleted() asynchronous callback, handle the fail case
         }
     }

     public void pauseApp()
     {
     }

     public void destroyApp(boolean unconditional)
     {
     }

     public void commandAction(Command c, Displayable s)
     {
     }

     public void productDataReceived(int status, IAPClientProductData pd)
     {
         if(status == OK)
         {
              String title = pd.getTitle();
              String price = pd.getPrice();
         }

         //Update UI with information
     }

     public void purchaseCompleted(int status, String purchaseTicket)
     {
         if(status == OK)
         {
              InputStream input = manager.getDRMResourceAsStream("/res/drm/data/ResourceId_123456");
              // Unlock game level 3, allow to be used
         }
     }

     public  void restorableProductsReceived(int status, IAPClientProductData[] productDataList)
     {
         if(status == OK)
         {
              for (int i = 0; i < productDataList.length; i++) {
                  // Access each product data:productDataList[i] 
              }
         }
     }

     public void restorationCompleted(int status, String purchaseTicket)
     {
         if(status == OK)
         {
              InputStream input = manager.getDRMResourceAsStream("/res/drm/data/ResourceId_112233");
              // Restore game level 5, allow to be used
         }
     }

     public void userAndDeviceDataReceived(int status, IAPClientUserAndDeviceData ud)
     {
         if(status == OK)
         {
              // Access client user and device data
         }
     }
 }

Field Summary

static int	DEFAULT_AUTHENTICATION The operation is executed as a normal one.
static int	FAIL
static int	FORCED_AUTOMATIC_RESTORATION The purchase request is automatically transformed to a restoration if item restoration is available.
static int	GENERAL_FAIL The operation has failed, do not expect an asynchronous callback later.
static int	KNI_INTERNAL_FAIL
static int	NO_FORCED_RESTORATION The purchase request does not restore the item.
static int	NORMAL
static int	NULL_INPUT_PARAMETER
static int	ONLY_IN_SILENT_AUTHENTICATION .
static int	OUT_OF_MEMORY
static int	PENDING_REQUEST
static int	PURCHASE
static int	RESTORE
static int	SIMULATION
static int	SUCCESS The operation is successful, expect an asynchronous callback at a later time when requested information is available.
static int	TEST_SERVER

Method Summary

java.io.InputStream	getDRMResourceAsStream(java.lang.String name) This provides the client application access to DRM encrypted resource files inside JAR.
static IAPClientPaymentManager	getIAPClientPaymentManager() Retrieve the singleton IAPClientPaymentManager instance
int	getProductData(java.lang.String productId) Provides information about purchasable items for the publisher application for building a catalog list.
int	getProductData(java.lang.String[] productIdList) Provides information about purchasable items for the publisher application for building a catalog list.
int	getRestorableProducts(int authenticationMode) Provides a list of Ovi Store items related to the given appId that are restorable via IAPClient API.
int	getUserAndDeviceId(int authenticationMode) Provides all necessary information about the current user and the device for the publisher service to restore non-Nokia DRM encrypted data to the device.
int	purchaseProduct(java.lang.String productId, int forceRestorationFlag) Initiates the purchase flow.
int	restoreProduct(java.lang.String productId, int authenticationMode) Initiates the restoration flow.
static void	setIAPClientPaymentListener(IAPClientPaymentListener iapListener) Set up a listener for IAP related events from the observed class IAPClientPaymentManager.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_AUTHENTICATION

public static final int DEFAULT_AUTHENTICATION

The operation is executed as a normal one. The user authentication is requested when necessary.

See Also:

Constant Field Values

ONLY_IN_SILENT_AUTHENTICATION

public static final int ONLY_IN_SILENT_AUTHENTICATION

. The operation is executed silently without the user authentication. If this is not possible, the operation is aborted If the user must enter account credentials, for example an account password, while ONLY_IN_SILENT_AUTHENTICATION is passed, the operation is aborted. Otherwise the operation continues regardless of whether the user has to enter account credentials or not.

See Also:

Constant Field Values

NO_FORCED_RESTORATION

public static final int NO_FORCED_RESTORATION

The purchase request does not restore the item.

See Also:

Constant Field Values

FORCED_AUTOMATIC_RESTORATION

public static final int FORCED_AUTOMATIC_RESTORATION

The purchase request is automatically transformed to a restoration if item restoration is available.

See Also:

Constant Field Values

SUCCESS

public static final int SUCCESS

The operation is successful, expect an asynchronous callback at a later time when requested information is available.

See Also:

Constant Field Values

GENERAL_FAIL

public static final int GENERAL_FAIL

The operation has failed, do not expect an asynchronous callback later.

See Also:

Constant Field Values

PENDING_REQUEST

public static final int PENDING_REQUEST

See Also:

Constant Field Values

NULL_INPUT_PARAMETER

public static final int NULL_INPUT_PARAMETER

See Also:

Constant Field Values

KNI_INTERNAL_FAIL

public static final int KNI_INTERNAL_FAIL

See Also:

Constant Field Values

OUT_OF_MEMORY

public static final int OUT_OF_MEMORY

See Also:

Constant Field Values

TEST_SERVER

public static final int TEST_SERVER

See Also:

Constant Field Values

SIMULATION

public static final int SIMULATION

See Also:

Constant Field Values

PURCHASE

public static final int PURCHASE

See Also:

Constant Field Values

RESTORE

public static final int RESTORE

See Also:

Constant Field Values

FAIL

public static final int FAIL

See Also:

Constant Field Values

NORMAL

public static final int NORMAL

See Also:

Constant Field Values

Method Detail

getIAPClientPaymentManager

public static IAPClientPaymentManager getIAPClientPaymentManager()
                                                          throws IAPClientPaymentException

Retrieve the singleton IAPClientPaymentManager instance

Returns:

The return is the instance of IAPClientPaymentManager singleton: The value is null if the singleton has already been initialized

Throws:

IAPClientPaymentException - if the Application ID can't be read out from JAR package

java.lang.SecurityException - if the caller does not have security permission to use In-App Purchase API

setIAPClientPaymentListener

public static void setIAPClientPaymentListener(IAPClientPaymentListener iapListener)

Set up a listener for IAP related events from the observed class IAPClientPaymentManager.

Parameters:

listener - of type IAPClientPaymentListener

getProductData

public int getProductData(java.lang.String productId)

Provides information about purchasable items for the publisher application for building a catalog list. The productDataReceived() callback returns a ProductData structure for each of the productIDs. The callback is sent only if the return value is SUCCESS. Upon success the method schedules a callback which is dispatched to the application at some suitable time instance in future.

Parameters:

productId - The productId of the purchaseable items. Publishers register sub-products(IAP) with Ovi store to receive product IDs

Returns:

The return is an integer value. The value is one of the following:

SUCCESS: The method call succeeded. IAP API sends the productDataReceived() callback to the publisher application. .

FAIL: The method call failed. IAP API does not send the productDataReceived() callback to the publisher application.

getProductData

public int getProductData(java.lang.String[] productIdList)

Provides information about purchasable items for the publisher application for building a catalog list. The productDataListReceived() callback returns ProductData structure for a list of requested productIDs. The callback is sent only if the return value is SUCCESS. Upon success the method schedules a callback which is dispatched to the application at some suitable time instance in future.

Parameters:

productIdList - The productIds of a list of purchaseable items. Publishers register sub-products(IAP) with Ovi store to receive product IDs

Returns:

The return is an integer value. The value is one of the following:

SUCCESS: The method call succeeded. IAP API sends the productDataListReceived() callback to the publisher application. .

FAIL: The method call failed. IAP API does not send the productDataListReceived() callback to the publisher application.

purchaseProduct

public int purchaseProduct(java.lang.String productId,
                           int forceRestorationFlag)

Initiates the purchase flow. If forceRestorationFlag is set and the item to be purchased is restorable, the purchase flow is automatically transformed to a restoration flow. Only Nokia DRM encrypted items can be restored using IAPClient API.

The function call results in the purchaseCompleted() callback during execution if the return value is positive: This provides the purchase result, when the Ovi Store back end has completed the purchase and the purchase data is available for the client application. Upon success the method schedules a callback which is dispatched to the application at some suitable time instance in future.

Parameters:

productId - The ID of the product to be purchased. Publishers register sub-products(IAP) with Ovi store to receive product IDs

forceRestorationFlag - the flag for selecting forcedRestoration when available Possible values are one of the constants defined in this class, NO_FORCED_RESTORATION or FORCED_AUTOMATIC_RESTORATION

Returns:

The return is an integer value. The value is one of the following:

SUCCESS: The method call succeeded. IAP API sends the purchaseCompleted() callback to the publisher application.

FAIL: The method call failed. IAP API does not send the purchaseCompleted() callback to the publisher application.

restoreProduct

public int restoreProduct(java.lang.String productId,
                          int authenticationMode)

Initiates the restoration flow. Only Nokia DRM encrypted items can be restored using IAPClient API. The function call results in the restorationCompleted() callback during the execution if the return value is positive This provides the result of the restoration, when it is completed by the Ovi Store back end and the restoration data is available for the client application. Upon success the method schedules a callback which is dispatched to the application at some suitable time instance in future.

Parameters:

productId - The ID of the product to be restored. Publishers register sub-products(IAP) with Ovi store to receive product IDs

authenticationMode - Defines whether product is being restored silently without asking the user authentication or not Possible values are one of the constants defined in this class, DEFAULT_AUTHENTICATION or ONLY_IN_SILENT_AUTHENTICATION

Returns:

The return is an integer value. The value is one of the following:

SUCCESS: The method call succeeded. IAP API sends the restorationCompleted() callback to the publisher application.

FAIL: The method call failed. IAP API does not send the restorationCompleted() callback to the publisher application.

getRestorableProducts

public int getRestorableProducts(int authenticationMode)

Provides a list of Ovi Store items related to the given appId that are restorable via IAPClient API. The restorableProductsReceived() callback function returns the list of restorable products. The callback function is called only if the return value is positive. Upon success the method schedules a callback which is dispatched to the application at some suitable time instance in future.

Parameters:

authenticationMode - Defines whether restorable products are fetched silently without asking the user authentication or not

Returns:

The return is an integer value. The value is one of the following:

SUCCESS: The method call succeeded. IAP API sends the restorableProductsReceived() callback to the publisher application. .

FAIL: The method call failed. IAP API does not send the restorableProductsReceived() callback to the publisher application.

getUserAndDeviceId

public int getUserAndDeviceId(int authenticationMode)

Provides all necessary information about the current user and the device for the publisher service to restore non-Nokia DRM encrypted data to the device. The userAndDeviceDataReceived() callback returns the data in hashed form. The callback is sent only if the return value is positive. Upon success the method schedules a callback which is dispatched to the application at some suitable time instance in future.

Parameters:

authenticationMode - Defines whether the user and the device data are fetched silently without asking user authentication or not Possible values are one of the constants defined in this class, DEFAULT_AUTHENTICATION or ONLY_IN_SILENT_AUTHENTICATION

Returns:

The return is an integer value. The value is one of the following:

SUCCESS: The method call succeeded. IAP API sends the userAndDeviceDataReceived() callback to the publisher application. .

FAIL: The method call failed. IAP API does not send the userAndDeviceDataReceived() callback to the publisher application.

getDRMResourceAsStream

public java.io.InputStream getDRMResourceAsStream(java.lang.String name)

This provides the client application access to DRM encrypted resource files inside JAR. eg. Possible location Jar-root/res/drm/data/level_1 /level_2 This is used after receiving the PurchaseTicket from a successful purchase flow or restoration flow. Finds a drm resource with a given name inside the application's JAR file. This method returns null if no resource with this name is found in the application's JAR file.

The resource names can be represented in two different formats: absolute or relative.

Absolute format:

/packagePathName/resourceName

Relative format:

resourceName

In the absolute format, the programmer provides a fully qualified name that includes both the full path and the name of the resource inside the JAR file. In the path names, the character "/" is used as the separator.

In the relative format, the programmer provides only the name of the actual resource. Relative names are converted to absolute names by the system by prepending the resource name with the fully qualified package name of class upon which the geDRMResourceAsStream method was called.

Parameters:

name - name of the desired resource

Returns:

a java.io.InputStream object.