GLLib: License Class Reference

GLLib

License Class Reference

The base class for License communication with the Gameloft server. More...

List of all members.

Public Member Functions

void cancel ()
 Cancels the ongoing request.
void cleanup ()
 Cleans up the memory allocated during the last server request.
int getLastError ()
 Gets the status of the last request.
boolean handleValidateLicense ()
 Cingular Specific - Handles the license validation request, after such a request has been initiated with sendValidateLicense(), this function's asynchronous pair.
boolean isLicenseValid ()
 License (MIDlet midlet)
void sendValidateLicense ()
 Cingular Specific - Sends a request to retreive the users license expiration time.

Static Public Attributes

static long callstarttime
 The time the current request started - used for timeout implementation.
static final int NOT_A_NUMBER = -666666
 Used to define anything that should be a number but it has not been initialised or does not have a value yet.

Classes

interface  Error
 License error codes. More...

Detailed Description

The base class for License communication with the Gameloft server.

Important notice : make sure the API connects to the corresponding servers!!! Ask interactivity team for the correct urls.


Control the set of features offered by the api using the Configuration interface.
The api consists of: Cingular License Validation

&nbsp &nbsp &nbsp &nbsp License

Provides services for validating a Cingular users subscription.

The main mechanism for passing requests to the Gameloft server is by using HTTP transactions. Every action that results in contacting the server has a pair of asynchronous functions, a send function and a handle.

The send function builds up the HTTP message with the request and initiates the transaction (sends that message to the server).

The handle manages the connection and any events that might occur, for example a response from the server, a timeout or an error. It sets an error code indicating the status of the current connection which can be viewed by the means of the getLastError() function provided.

This means that the usual cycle of a request is the following:
1. initiate the transaction by sending the request
2. while the result from the server is pending and a timeout has not occured, call the handle and check the error code returned with getLastError();
3. analysing the error code returned, determine a correct response (if the result is still pending, wait some more, if timedout or some other error display a meaningful message, etc.)

NOTE: Since subscriptions will not work when testing the games the testing server will randomly return:

  • Valid for 12 hours 80% of the time.
  • License Expired 25% of the time.
  • Error 5% of the time.

Following is a short example of a generic game License Validation code:

The process for license validation is different then that of the standard
XPlayer imlementation. This is because it has to run before the game is
even start and has to be as efficient as possible. The code that should be
add before the game is started follows:

   License xplayer = new License(midlet_);

Check to see if the license stored in RMS is valid.
   if (xplayer.isLicenseValid())
   {
The license is good!
      ...// TODO: Start the game.
      System.out.println("License valid, start the game!");
   }

   else
   {
Check with server to see if MRC has been renewed.
      xplayer.sendValidateLicense();

We call the handle
and get the error code returned by it.
      while (xplayer.handleValidateLicense() != true)
      {
Wait for the response.

         ...// TODO: Here there should be a test on a keypress event which, if true,
would call the cancel() method of the XPlayer class,
canceling any request; this would provide the user with an
option to cancel the transaction.
      }

Get the error.
      int _errCode = xplayer.getLastError();

      xplayer.cleanup();

Verify response from server.
      switch (_errCode)
      {
         case XPlayer.Error.ERROR_NONE:
Successful response.
Check to see if the new license stored in RMS is valid.
            if (xplayer.isLicenseValid())
            {
The license is good!
               ...// TODO: Start the game.
               System.out.println("License valid, start the game!");
            }
            else
            {
License has expired.
               ...// TODO: Let the user know and don't start the game.
               System.out.println("License Expired.");
            }
            break;

         case XPlayer.Error.ERROR_CONNECTION:
A connection error occured
And either the timestamp in RMS has expired or the RMS
doesn't exist.

            ...// TODO: An error message should be displayed and an
option to retry provided.
            System.out.println("Connection error. Please try again later.");
            break;

         default:
Some other error occured.
And either the timestamp in RMS has expired or the RMS
doesn't exist.

            ...// TODO: An error message should be displayed and an
option to retry provided.
            System.out.println("Some other network error. Please try again later.");
            break;
      }
   } // End of else

 

Author:
Gameloft Interactivity Team
Version:
1.0.0

Copyright:

Gameloft SA (C) 2005


Constructor & Destructor Documentation

License ( MIDlet  midlet  ) 

Constructor for the XPlayer class.

It reads the values of the XPlayerURL and GGI properties from the .jad file of midlet for initialisation purposes.

Parameters:
midlet Reference to the MIDlet of the game which implements this API.


Member Function Documentation

void cancel (  ) 

Cancels the ongoing request.

void cleanup (  ) 

Cleans up the memory allocated during the last server request.

Use this everytime a request completes (it finishes being pending - check with getLastError()) to free up some memory.

See also:
getLastError()

int getLastError (  ) 

Gets the status of the last request.

Call this after any handle function to find out the status of the request.

If ERROR_PENDING is returne, the call is still in progress.

Returns:
One of the error codes defined in the XPlayer.Error interface depending on the last request's status.
See also:
XPlayer.Error

boolean handleValidateLicense (  ) 

Cingular Specific - Handles the license validation request, after such a request has been initiated with sendValidateLicense(), this function's asynchronous pair.

 This function is valid only for Cingular games

This license validation is only for Cingular games. This is not supported for other operators so it shouldn't be used on them.

See also:
handleValidateLicense()

boolean isLicenseValid (  ) 

void sendValidateLicense (  ) 

Cingular Specific - Sends a request to retreive the users license expiration time.

 This function is asynchronous and valid only for Cingular games.

Use handleValidateLicense() to handle the request afterwards.

This license validation is only for Cingular games. This is not supported for other operators so it shouldn't be used on them.

See also:
sendValidateLicense()


Member Data Documentation

long callstarttime [static]

The time the current request started - used for timeout implementation.

Use only in conjunction with ENABLE_TIMEOUT.

final int NOT_A_NUMBER = -666666 [static]

Used to define anything that should be a number but it has not been initialised or does not have a value yet.

For example when the user inquires about his score for a level that he has never played yet or anything similar.


Generated on Tue Sep 23 23:05:32 2008 for GLLib by  doxygen 1.5.2