C H A P T E R 10

Subscriber API

The Subscriber API provides access to data maintained by the Content Delivery Server. Use this API to get the data needed to create your own client application for providing subscribers with access to content managed by the Content Delivery Server.

Clients that are written in the Java programming language and located on a server with the Subscriber Portal component of the Content Delivery Server can call the Subscriber API directly. Clients written in a language other than Java, or clients that are located on a server that does not contain the Subscriber Portal must access the Subscriber API through the XML-RPC (remote procedure call) implementation.

The Subscriber API includes the following classes and interfaces that your client might use:

ApiContextFactory - Class that creates an IApiContext object that contains the characteristics of the subscriber, such as locale, device model, and mobile ID.

ApiServiceFactory - Class that creates a service for a specific subscriber. Services provide access to a collection of related information. For example, the Content Service provides access to the list of previous purchases made by a subscriber, the details of individual items, and a subscriber's bookmarked contents.

ApiUtil - Class that provides utilities such as initiating a transaction or checking the version of the database.

IApiContext - Interface that provides information about the current subscriber.

ICategoryService - Interface that provides access to the category tree and a subscriber's category list.

IContentService - Interface that provides access to content for browsing, searching, retrieving, and purchasing.

IDownloadService - Interface that provides access to content descriptors.

IGiftingService - Interface that enables a subscriber to send gifts or messages about an item to another subscriber.

IMessageService - Interface that enables messages to be sent to this subscriber or another subscriber. Messages can be in email, MMS, SMS, or WAP push formats.

ISystemService - Interface that provides access to system-level content such as locales, content types, and device models.

IUserService - Interface that provides access to information on subscribers and enables new subscriber accounts to be created.

CDSException - Exception thrown by the Subscriber API if an error occurs.

For additional information on these and other classes, see the HTML output of the Javadoc tool at $CDS_HOME/javadoc/subscriberapi/index.html.

10.1 General Process Flow

This section describes general tasks that you might want your client application to perform. The class names used in this section refer to the classes that make up the Subscriber API. See Section 10.3, XML-RPC Implementation for the equivalent handler if you are accessing the Content Delivery Server data using XML-RPC.

In general, the client application that you create for your subscriber interface includes actions such as those described in the following list.

Create an IApiContext object by calling ApiContextFactory.

The IApiContext object describes either a specific subscriber or an anonymous subscriber. This object is used by all services to retrieve data specific to the subscriber described by the object. Typically, you would create the IApiContext object once per user session and store it in the HttpSession object. See Section 10.2.2, Example of Creating an IApiContext Object for sample code.

Create the services that you need to obtain the information that you want to use by calling the ApiServiceFactory.

The services that you create depend on the tasks that you want to perform. For example, to enable a subscriber to purchase a gift for another subscriber, create an IGiftingService object. To provide a subscriber with the list of content already purchased, create an IContentService object. You must have an IApiContext object to create a service. Each service created provides data specific to the subscriber described by the IApiContext object. See Section 10.2.3, Example of Creating a Service for sample code.

Retrieve the information that you want to use by calling the methods for the services that you created.

For example, if you created an IContentService, call getCampaigns() to get the list of campaigns available to the subscriber or getPurchases() to get the list of items that the subscriber has already purchased.

10.2 Using the Subscriber API

The classes for the Subscriber API are in the package com.sun.content.server.subscriberapi. This package is included in the subscriberportal.jar file in one of the following locations:

For Sun Java System Application Server, in $CDS_HOME/deployment/deployment-name/sun/domains/server-domain/server-name/applications/j2ee-modules/CDSSubscriberPortal/WEB-INF/lib.

For WebLogic Server, in $CDS_HOME/deployment/deployment-name/weblogic/domains/server-domain/applications/subscriber/WEB-INF/lib.

deployment-name is the name specified when the Catalog Manager was deployed, server-domain is the value specified in the deployment configuration file for the app.server.domain property and server-name is the value specified in the deployment configuration file for the app.server.name property.

If your client application is a Java application, create your client using the Subscriber API classes in the subscriberportal.jar file. This JAR file must be in your classpath when you compile your application.

To execute, place the JAR file that contains your client in the same $CDS_HOME/deployment/deployment-name/.../lib directory that contains the subscriberportal.jar file. Your client must run within the same web application structure as the Subscriber Portal provided with the Content Delivery Server. Stand-alone Java applications are not supported.

If your client is not a Java application or will not be located on the same server as the Subscriber Portal, see Section 10.3, XML-RPC Implementation for information on accessing the Subscriber API through XML-RPC.

10.2.1 Managing Transactions

A transaction occurs each time you create an instance of a service and call its methods to perform a task. Your application must manage the transactions with the Content Delivery Server as described in the following steps:

1. Before a service is invoked, call ApiUtil.initTransaction() to indicate the start of a transaction.

2. If the transaction completes successfully, call ApiUtil.commitTransaction() to commit the work done. If an error occurs during the transaction, call ApiUtil.rollbackTransaction() to terminate the work and restore the data to its previous state.

3. The transaction resources must be released in a finally block that calls ApiUtil.disposeTransaction().

See the code examples in Section 10.2.2, Example of Creating an IApiContext Object and Section 10.2.3, Example of Creating a Service for sample implementations.

10.2.2 Example of Creating an `IApiContext` Object

The following code excerpt shows how to create an IApiContext object.

CODE EXAMPLE 10-1 Create an `IApiContext` Object Using Java Classes
... try { // Open a Transaction ApiUtil.initTransaction(); // Create a map of credentials (from user input) Properties credentials = new Properties(); credentials.put(ApiContextFactory.CREDENTIAL_USERNAME, username); credentials.put(ApiContextFactory.CREDENTIAL_PASSWORD, password); // Attempt to authenticate using the credentials IApiContext apiContext = ApiContextFactory.createApiContext(credentials); // Save the IApiContext in the HttpSession session.setAttribute("API_CONTEXT", apiContext); // Commit the Transaction ApiUtil.commitTransaction(); } catch (CDSException e) { // Rollback the Transaction ApiUtil.rollbackTransaction(); // Evaluate the exception's error code if(e.getErrorCode().equals(CDSException.CDS_EX_SUBSCRIBER_DISABLED) { // handle disabled user ... } else { // handle API Exception ... } } finally { // clean up Transaction ApiUtil.disposeTransaction(); } ...

CODE EXAMPLE 10-1 Create an IApiContext Object Using Java Classes

...

try

  // Open a Transaction

  ApiUtil.initTransaction();

  // Create a map of credentials (from user input)

  Properties credentials = new Properties();

  credentials.put(ApiContextFactory.CREDENTIAL_USERNAME, username);

  credentials.put(ApiContextFactory.CREDENTIAL_PASSWORD, password);

  // Attempt to authenticate using the credentials

  IApiContext apiContext = ApiContextFactory.createApiContext(credentials);

  // Save the IApiContext in the HttpSession

  session.setAttribute("API_CONTEXT", apiContext);

  // Commit the Transaction

  ApiUtil.commitTransaction();

catch (CDSException e)

  // Rollback the Transaction

  ApiUtil.rollbackTransaction();

  // Evaluate the exception's error code

  if(e.getErrorCode().equals(CDSException.CDS_EX_SUBSCRIBER_DISABLED)

    // handle disabled user

...

  else

    // handle API Exception

...

finally

  // clean up Transaction

  ApiUtil.disposeTransaction();

...

10.2.3 Example of Creating a Service

The following code excerpt shows how to create a Content Service and use that service to purchase content.

CODE EXAMPLE 10-2 Create a Service
... try { // Open a Transaction ApiUtil.initTransaction(); // Retrieve the IApiContext from the HttpSession IApiContext apiContext = (IApiContext) session.getAttribute("API_CONTEXT"); // Get a reference to a Content Service IContentService cs = ApiServiceFactory.getContentService(apiContext); // Attempt to purchase a content item as part of a campaign cs.purchaseContent(contentId, campaignId, true); // Commit the Transaction ApiUtil.commitTransaction(); } catch (CDSException e) { // Rollback the Transaction ApiUtil.rollbackTransaction(); // Handle API Exception ... } finally { // Clean up Transaction ApiUtil.disposeTransaction(); } ...

CODE EXAMPLE 10-2 Create a Service

...

try

  // Open a Transaction

  ApiUtil.initTransaction();

  // Retrieve the IApiContext from the HttpSession

  IApiContext apiContext = (IApiContext) session.getAttribute("API_CONTEXT");

  // Get a reference to a Content Service

  IContentService cs = ApiServiceFactory.getContentService(apiContext);

  // Attempt to purchase a content item as part of a campaign

  cs.purchaseContent(contentId, campaignId, true);

  // Commit the Transaction

  ApiUtil.commitTransaction();

catch (CDSException e)

  // Rollback the Transaction

  ApiUtil.rollbackTransaction();

  // Handle API Exception

...

finally

  // Clean up Transaction

  ApiUtil.disposeTransaction();

...

10.3 XML-RPC Implementation

If your client is not a Java application or is not running on the server with Content Delivery Server, your client must communicate with the Content Delivery Server using XML-RPC. XML-RPC enables your client to make remote procedure calls using HTTP for the transport and XML for data encoding. You can use XML-RPC with many different programming languages by using bindings available on the Internet. All of the functionality of the Subscriber API is available through XML-RPC.

Note - A tutorial on XML-RPC is beyond the scope of this document. Information on writing applications that use XML-RPC is available from various web sites on the Internet.

10.3.1 Accessing the Content Delivery Server

To obtain data from the Content Delivery Server, your client must be able to communicate with the Content Delivery Server. Work with your network administrator to ensure that the client can contact the Content Delivery Server and that any required proxy or firewall is configured to allow this access.

In addition, the Content Delivery Server must recognize that your client is authorized to make requests for data. The subscriberApi.xml-rpc.trustedHosts property in the $CDS_HOME/deployment/deployment-name/conf/SubscriberPortal.properties file contains the list of hosts from which requests are accepted.

Set the subscriberApi.xml-rpc.trustedHosts property to the host name or IP address of the host on which your client is located, whether it is on the same host as the Content Delivery Server or on a different host. To accept requests from any host, leave the value blank. To accept requests from more than one host, separate the host names or IP addresses with a comma, for example:

subscriberApi.xml-rpc.trustedHosts=127.0.0.1,localhost

10.3.2 Using XML-RPC Handlers for the Subscriber API

The general flow of your application (see Section 10.1, General Process Flow) is the same whether you access the Subscriber API directly or through XML-RPC. Handlers in the XML-RPC implementation perform the same functions as the Subscriber API services. Each handler and its corresponding service have equivalent methods with equivalent parameters.

The following topics are presented in this section:

Guidelines for Calls to XML-RPC Methods

AuthenticationHandler

CategoryHandler

ContentHandler

DownloadHandler

GiftingHandler

MessageHandler

SystemHandler

UserHandler

Parameters for the Methods

10.3.2.1 Guidelines for Calls to XML-RPC Methods

Use the following guidelines to code your calls to the handlers. The sample code is written in the Java programming language.

Place the parameters for the method that you are calling in a hash table. Place the hash table in a vector.

...

// Set up the input parameters

Vector parameters = new Vector();

Hashtable ht = new Hashtable();

ht.put("username", "user1");

ht.put("password", "cryptic1");

parameters.addElement(ht);

...

To call a method, pass the name of the method and the vector that you created for the hash table that contains the parameters. A hash table is returned. The method call must include the name of the handler, for example: AuthenticationHandler.getApiContext.

...

// Send the request to Content Delivery Server

Hashtable response = (Hashtable) client.execute("AuthenticationHandler.getApiContext", parameters);

...

Verify that the method executed successfully by checking the response code that is included in the hash table that is returned. If an error occurred, a response message is also included in the hash table.

...

// Evaluate the response

String errorCode = (String)response.get("response_code");

if (!errorCode.equals("1"))

  // Handle Error

  System.out.println((String)response.get("response_message"));

If the method executes successfully, extract the values that are returned in the hash table. If a method does not return any values, the hash table contains only the response code.

...

  // Authentication successful

  Hashtable apiContext = (Hashtable)response.get("apiContext");

  Integer subscriberId = (Integer)apiContext.get("subscriberId");

  String username = (String)apiContext.get("username");

  String localeCode = (String)apiContext.get("localeCode");

  String mobileId = (String)apiContext.get("mobileId");

  Integer modelId = (Integer)apiContext.get("modelId");

...

The following sections describe the handlers that you can use. Examples are provided in Section 10.3.3, Examples of Using Handlers.

10.3.2.2 `AuthenticationHandler`

AuthenticationHandler is equivalent to the APIContextFactory class. This handler creates the object that contains the characteristics of the subscriber. The guidelines for calling a method in a handler are described in Section 10.3.2.1, Guidelines for Calls to XML-RPC Methods. To call a method, concatenate the name of the handler with the name of the method, for example:

AuthenticationHandler.getApiContext

The following table describes the AuthenticationHandler methods.

TABLE 10-1 Methods for `AuthenticationHandler`
Method Name	Description	Parameters	Returns¹
`getAnonymousApiContext`	Create an `APIContext` object for an anonymous subscriber.	localeCode, modelId	apiContext
`getApiContext`	Authenticate the subscriber based on the information provided and create an `APIContext` object that contains the information for that subscriber.	One of the following items: username and password mobileId uniqueId subscriberId requestHeaders	apiContext
¹ In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.

10.3.2.3 `CategoryHandler`

CategoryHandler is equivalent to the ICategoryService interface. This handler provides access to the category tree and a subscriber's category list. The guidelines for calling a method in a handler are described in Section 10.3.2.1, Guidelines for Calls to XML-RPC Methods. To call a method, concatenate the name of the handler with the name of the method, for example:

CategoryHandler.getCategory

The following table describes the CategoryHandler methods.

TABLE 10-2 Methods for `CategoryHandler`
Method Name	Description	Parameters	Returns¹
`getCategory`	Get the specified category for the current subscriber.	apiContext, categoryId, includeContentCount	category
`getCategoryBranch`	Get an entire branch of the category tree beginning with the category specified in `categoryId`. To get the entire tree, specify the root category.	apiContext, categoryId, includeContentCount	category
`getNotEmptySubCategories`	For the category specified in `categoryId`, get the list of subcategories that contain the type of content listed in `contentTypeIdList` with a status listed in `statusList`. If `contentTypeIdList` is not provided, all content types are considered. If `statusList` is not provided, all statuses are considered.	apiContext, categoryId, contentTypeIdList (optional), statusList (optional), includeContentCount	categoryList
`getSubCategories`	For the category specified in `categoryId`, get the list of all subcategories.	apiContext, categoryId, includeContentCount	categoryList
`getRootCategory`	Get the root category for the current subscriber.	apiContext, includeContentCount	category
`hideCategory`²	Hide the categories specified in `categoryIds` that the subscriber has chosen to not view and return the updated list.	apiContext, categoryIds, categoryList	categoryList
`moveCategoryDown`²	Move each category specified in `categoryIds` down one position below the next active category and return the updated list.	apiContext, categoryIds, categoryList	categoryList
`moveCategoryUp`²	Move each category specified in `categoryIds` up one position above the next active category and return the updated list.	apiContext, categoryIds, categoryList	categoryList
`showCategory`²	Show the categories specified in `categoryIds` that the subscriber has selected and return the updated list.	apiContext, categoryIds, categoryList	categoryList
`updateCategories`	Update the information in the database for the categories in `categoryList`.	apiContext, categoryList	None
¹ In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message. ² This method changes the category list held in memory. To make the changes permanent, you must call `updateCategories`.

10.3.2.4 `ContentHandler`

ContentHandler is equivalent to the IContentService interface. This handler provides access to the content for browsing, searching, retrieving, and purchasing. The guidelines for calling a method in a handler are described in Section 10.3.2.1, Guidelines for Calls to XML-RPC Methods. To call a method, concatenate the name of the handler with the name of the method, for example:

ContentHandler.browseContent

The following table describes the ContentHandler methods.

TABLE 10-3 Methods for `ContentHandler`
Method Name	Description	Parameters	Returns¹
`addBookmark`	Add an item of content to the subscriber's list of bookmarked content.	apiContext, contentId	None
`browseContent`	Get the number of items specified in `numberToReturn` in the category specified in `categoryId` that are of the types specified in `contentTypeIdList`. If `contentTypeIdList` is not provided, all content types are included.	apiContext, categoryId, contentTypeIdList (optional), startIndex, numberToReturn	contentList, totalSize
`cancelSubscription`	Cancel the subscriber's subscription to an item of content.	apiContext, contentId	None
`clearBookmarks`	Clear a subscriber's list of bookmarked content.	apiContext	None
`deleteBookmark`	Delete an item of content from the subscriber's list of bookmarked content.	apiContext, contentId	None
`getAnonymousCampaignForCoupon`	Get the information for a campaign that is associated with the coupon specified. Call this method if the subscriber is anonymous.	apiContext, couponCode	campaign
`getBookmarks`	Get the list of items the subscriber has bookmarked.	apiContext	contentList
`getBundledItems`	Get the items of content in a bundle.	apiContext, contentId, criteria	contentList, totalSize
`getBundledItems`	Get the items of content in a bundle. Note: This method is deprecated. Use the new version.	apiContext, contentId	contentList, totalSize
`getCampaign`	Get the information for a campaign.	apiContext, campaignId	campaign
`getCampaignForCoupon`	Get the information for a campaign that is associated with the coupon specified. Call this method if the subscriber is known.	apiContext, couponCode	campaign
`getCampaignItems`	Get the list of content associated with the campaign.	apiContext, campaignId, startIndex, numberToReturn	contentList, totalSize
`getCampaigns`	Get the list of campaigns that are available to the subscriber.	apiContext	campaignList
`getContentByClassId`	Get the content ID for a specific edition of the content identified by `contentId`.	apiContext, contentId	contentId
`getContentByKeyword`	Get the content ID for a specific edition of the content identified by `contentKeyword`.	apiContext, contentKeyword	contentId
`getContentDetails`	Get the information about an item of content.	apiContext, contentId, criteria	content
`getContentDetails`	Get the information about an item of content. Note: This method is deprecated. Use the new version.	apiContext, contentId, campaignId (optional), bundleId (specify only if the content is part of a bundle), isSkipTrial, filter	content
`getContentDetailsCriteria`	Get an empty criteria object, which can be used for methods that accept criteria as a parameter.	apiContext	criteria
`getContentDetailsList`	Get the information for each item of content specified in `contentIdList`.	apiContext, contentIdList, criteria	contentList
`getContentSummary`	Get summary information for an item of content.	apiContext, contentId	contentSummary
`getDeliveryType`	Get the type of delivery used to deliver this content.	apiContext, contentId	deliveryType
`getPurchasedBundles`	Get the list of bundles purchased by the subscriber that contain the item of content specified in `contentId`.	apiContext, contentId	contentList, totalSize
`getPurchases`	Get the list of content that the subscriber has purchased.	apiContext	purchaseList
`getSupportedModels`	Get the list of models on which the content can run.	apiContext, contentId	modelList
`getTicket`	Get the purchase ticket for the content identified by `contentId`.	apiContext, contentId	codedTicket
`hasPurchases`	Determine if the subscriber purchased any content.	apiContext	hasPurchases
`isBookmarked`	Determine if the subscriber bookmarked the content.	apiContext, contentId	isBookmarked
`isContentInCampaign`	Determine if the content specified in `contentId` is in the campaign specified in `campaignId`.	apiContext, contentId, campaignId	isContentInCampaign
`isMMSCapable`	Determine if the content can be pushed to the device using MMS.	apiContext, contentId	isMMSCapable
`isSMSCapable`	Determine if the content can be pushed to the device using SMS.	apiContext, contentId	isSMSCapable
`purchaseContent`	Purchase content that is part of a campaign. Not available for anonymous subscribers.	apiContext, contentId, campaignId (optional), isSkipTrial	None
`requestContent`	Send content to a subscriber. Content must first be purchased.	apiContext, contentId, requestParams, maxNumberToSend	wasDelivered
`searchContent`	Get the list of content that matches the search criteria. The category tree is searched beginning with the category specified in `categoryId`. To search all content, specify the root category (see the getRootCategory method in `CategoryHandler`.)	apiContext, categoryId, contentTypeIdList (optional), keyword, startIndex, numberToReturn	contentList, totalSize
¹ In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.

10.3.2.5 `DownloadHandler`

DownloadHandler is equivalent to the IDownloadService interface. This handler provides access to the descriptors needed to download content. The guidelines for calling a method in a handler are described in Section 10.3.2.1, Guidelines for Calls to XML-RPC Methods. To call a method, concatenate the name of the handler with the name of the method, for example:

DownloadHandler.downloadConfirm

The following table describes the DownloadHandler methods.

TABLE 10-4 Methods for `DownloadHandler`
Method Name	Description	Parameters	Returns¹
`downloadConfirm`	Confirm if the content was downloaded to the device.	apiContext, codedTicket, isOneStepConfirm, status	None
`downloadContent`	Download the binary file for the item of content specified by `contentId`.	apiContext, contentId	contentLength, contentType, descriptorData
`downloadContentDescriptor`	Create a content descriptor file and return it to the caller.	apiContext, codedTicket	contentLength, contentType, descriptorData
`downloadDelete`	Delete content from a device.	apiContext, codedTicket, isOneStepConfirm, status	None
`downloadJAD`	Create a Java Application Descriptor (JAD) file and return it to the caller.	apiContext, codedTicket	contentLength, contentType, descriptorData
`downloadJAM`	Create an application descriptor file for an iAppli application and return it to the caller.	apiContext, codedTicket	contentLength, contentType, descriptorData
`pushMMSContent`	Push content to the device using MMS.	apiContext, contentId	None
`pushMMSContentByTicket`	Push content identified by `codedTicket` to the device using MMS.	apiContext, codedTicket	None
`pushSMSContentBinary`	Push external content to the device using SMS.	apiContext, mobileId, contentBinary, mimeType, contentType, smsParams	None
`pushSMSContentByTicket`	Push content identified by `codedTicket` to the device using SMS.	apiContext, codedTicket, smsParams	None
`sendInstall`	Push content installation file to a subscriber's device.	apiContext, contentId, bundleId	None
¹ In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.

10.3.2.6 `GiftingHandler`

GiftingHandler is equivalent to the IGiftingService interface. This handler enables gifts or notifications about content to be sent to another subscriber. The guidelines for calling a method in a handler are described in Section 10.3.2.1, Guidelines for Calls to XML-RPC Methods. To call a method, concatenate the name of the handler with the name of the method, for example:

GiftingHandler.createGifting

The following table describes the GiftingHandler methods.

TABLE 10-5 Methods for `GiftingHandler`
Method Name	Description	Parameters	Returns¹
`cancelGifting`	Cancel a gift subscription.	apiContext, giftId	None
`checkAndExpireGifting`	Determine if the gift is expired.	apiContext, gifting	isGiftExpired
`getGiftingById`	Get the information about the gift specified by `giftId`.	apiContext, giftId, filter, bundledContentId	gifting
`getGiftingByTicket`	Get the information about the gift specified by `giftTicket`.	apiContext, giftTicket, filter, bundledContentId	gifting
`getGiftingsByGifter`	Get the information for all of the gifts given by the subscriber.	apiContext, filter	giftingList
`getGiftingsByRecipient`	Get the information for all of the gifts received by the subscriber.	apiContext, filter	giftingList
`giftContent`	Purchase an item of content as a gift for another subscriber.	apiContext, contentId, campaignId (optional), recipientApiContext, message, giftedDownloads, giftedSubscriptions	giftId
`isGiftingUsed`	Determine if the recipient claimed all of the uses provided by the gift.	apiContext, gifting	isGiftingUsed
`messageContent`	Send a message about an item of content to another subscriber.	apiContext, contentId, recipientApiContext, message	giftId
¹ In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.

10.3.2.7 `MessageHandler`

MessageHandler is equivalent to the IMessageService interface. This handler enables email, SMS, WAP push, and MMS messages to be sent to the current subscriber or to another subscriber. The guidelines for calling a method in a handler are described in Section 10.3.2.1, Guidelines for Calls to XML-RPC Methods. To call a method, concatenate the name of the handler with the name of the method, for example:

MessageHandler.sendMessageToSelf

The following table describes the MessageHandler methods.

TABLE 10-6 Methods for `MessageHandler`
Method Name	Description	Parameters	Returns¹
`sendMessageToMobileId`	Send a message to the number specified by the mobile ID provided.	apiContext, subject, message, url, mobileId, contentId, messageCategory	None
`sendMessageToSelf`	Send a message to the current subscriber.	apiContext, messageType, subject, message, url, contentId, messageCategory	None
`sendMessageToSubscriberId`	Send a message to the subscriber identified by the subscriber ID provided.	apiContext, messageType, subject, message, url, subscriberId, contentId, messageCategory	None
`sendMessageToUsername`	Send a message to the subscriber identified by the user name provided.	apiContext, messageType, subject, message, url, username, contentId, messageCategory	None
`sendMMSContent`	Send content to the current subscriber using MMS push.	apiContext, mobileId, contentBinary, name, contentType, mimeType, subject, message, modelId, contentId, messageCategory	None
¹ In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.

10.3.2.8 `SystemHandler`

SystemHandler is equivalent to the ISystemService interface. This handler provides access to system-level data such as content types, locales, and models. The guidelines for calling a method in a handler are described in Section 10.3.2.1, Guidelines for Calls to XML-RPC Methods. To call a method, concatenate the name of the handler with the name of the method, for example:

SystemHandler.getContentTypes

The following table describes the SystemHandler methods.

TABLE 10-7 Methods for `SystemHandler`
Method Name	Description	Parameters	Returns¹
`createTicket`	Create a ticket for a subscriber to use to retrieve an item of content.	apiContext, contentId	ticket
`getContentTypes`	Get a list of all of the content types that are defined in the Content Delivery Server.	apiContext	contentTypeList
`getCountries`	Get a list of all of the countries that are included in the Content Delivery Server.	apiContext	countryList
`getCountry`	Get the information for a single country.	apiContext, countryCode	country
`getDefaultLocale`	Get the default locale for the system.	apiContext	locale
`getDefaultMode`l	Get the default device model.	apiContext	modelId
`getLocale`	Get the information for a single locale.	apiContext, localeCode	locale
`getLocales`	Get a list of all of the locales included in the Content Delivery Server.	apiContext	localeList
`getManufacturers`	Get the names of all of the device manufacturers included in the Content Delivery Server.	apiContext	manufacturerList
`getModel`	Get the information for a device.	apiContext, modelId	model
`getModelId`	Get the internal ID for the device associated with the user agent specified in `modelId`.	apiContext, userAgent	modelId
`getModels`	Get a list of all of the devices supported by the Content Delivery Server.	apiContext	modelList
`getModelsForManufacturer`	Get the models in the Content Delivery Server for a given manufacturer. Only models that are not quarantined are returned.	apiContext, manufacturer	modelList
`isPushEnabled`	Determine if the subscriber's device is push enabled.	apiContext, modelId	isPushEnabled
`isTicketValid`	Determine if the ticket for an item of content can be used by the subscriber.	apiContext, ticket, contentId	isTicketValid
`sendEvent`	Send the system event specified in `eventType`. Note: This method is deprecated. The functionality is no longer required.	apiContext, subscriberId, mobileId, contentId (optional), eventType	None
`sendEventWithParameters`	Send a system event with a set of event parameters.	apiContext, requestParams	None
¹ In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.

10.3.2.9 `UserHandler`

UserHandler is equivalent to the IUserService interface. This handler provides access to information on subscribers and enables new subscriber accounts to be created. The guidelines for calling a method in a handler are described in Section 10.3.2.1, Guidelines for Calls to XML-RPC Methods. To call a method, concatenate the name of the handler with the name of the method, for example:

UserHandler.getSubscriberId

The following table describes the UserHandler methods.

TABLE 10-8 Methods for `UserHandler`
Method Name	Description	Parameters	Returns¹
`disableSubscriberBySubscriberId`	Disable the account for the subscriber identified by the subscriber ID.	apiContext, subscriberId	None
`disableSubscriberByUsername`	Disable the account for the subscriber identified by the user name.	apiContext, username	None
`getSubscriberId`	Get the subscriber ID for the subscriber identified by the user name.	apiContext, username	subscriberId
`getUserPreferences`	Get the preferences set by the subscriber.	apiContext	preferenceList
`getUserProperties`	Get the information for the current subscriber.	apiContext	propertyList
`getUserPropertiesBySubscriberId`	Get the information for the subscriber identified by the subscriber ID.	apiContext, subscriberId	propertyList
`getUserPropertiesByUsername`	Get the information for the subscriber identified by the user name.	apiContext, username	propertyList
`provision`	Populate a subscriber account in the Content Delivery Server with information from an external subscriber database.	apiContext, uniqueId, modelId, mobileId, localeCode	subscriberId
`resetPasswordBySubscriberId`	Set the password for the subscriber identified by the subscriber ID to a value generated by the system.	apiContext, subscriberId, passwordRequiresReset	password
`resetPasswordByUsername`	Set the password for the subscriber identified by the user name to a value generated by the system.	apiContext, username, passwordRequiresReset	password
`setLocaleCode`	Change the subscriber's locale code.	apiContext, localeCode	None
`setModelId`	Change the model ID to match the new device that the subscriber is using.	apiContext, modelId	None
`setPassword`	Change the subscriber's password.	apiContext, password	None
`setUserPreferences`	Set the preferences selected by a subscriber. These preferences manage the information that is shown to the user.	apiContext, preferenceList	None
`setUserProperties`	Set the information for a subscriber.	apiContext, propertyList	None
`signup`	Create a subscriber account in the Content Delivery Server and in any external subscriber database.	apiContext, username, password, modelId, mobileId, uniqueId, localeCode	subscriberId
`signupWithPropertiesAndPreferences`	Create a subscriber account in the Content Delivery Server and in any external subscriber database and set the information and preferences for that subscriber.	apiContext, username, password, modelId, mobileId, uniqueId, localeCode, propertyList, preferenceList	subscriberId
¹ In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.

10.3.2.10 Parameters for the Methods

The following table describes the parameters for the methods. Container objects such as Hashtable and Vector contain elements that are also described in the table.

TABLE 10-9 Method Parameters
Parameter	Type	Description
`addressLine1`	`String`	First line of a subscriber's address.
`addressLine2`	`String`	Second line of a subscriber's address.
`apiContext`	`Hashtable`	Container for the information about a subscriber. This container includes the following items: subscriberId username localeCode mobileId uniqueId modelId isAnonymous isProvisioned isRegistered passwordRequiresReset isCategoryCustomized roleId propertyMap Note: For an anonymous subscriber, only `subscriberId`, `localeCode`, and `modelId` are included.
`bundledContentId`	`Integer`	Internal ID that was assigned by the Content Delivery Server to an individual item in a bundle.
`bundleId`	`Integer`	Internal ID that was assigned by the Content Delivery Server to the bundle with which you are working.
`campaign`	`Hashtable`	Container for the information about a campaign. This container includes the following items: campaignId name description campaignSubject campaignMessage campaignDiscount campaignExpiration
`campaignDiscount`	`Double`	Percentage by which the items in the campaign are discounted.
`campaignExpiration`	`Date`	Date that the campaign expires. If the campaign is expired, `null` is returned.
`campaignId`	`Integer`	Internal ID that was assigned by the Content Delivery Server to the campaign with which you are working.
`campaignList`	`Vector`, elements of type campaign	List of campaigns available to the subscriber.
`campaignMessage`	`String`	Promotional message included in the notifications sent to subscribers to announce the campaign.
`campaignSubject`	`String`	Subject added to email notifications sent to subscribers to announce the campaign.
`category`	`Hashtable`	Container for information about a category. This container includes the following items: categoryId name description parentCategoryId isLeafNode isActive displayOrder contentCount subCategoryList (only included if returned by the getCategoryBranch method of `CategoryHandler`)
`categoryId`	`Integer`	Internal ID that was assigned by the Content Delivery Server to the category with which you are working.
`categoryIds`	`Vector`, elements of type `Integer`	List of category IDs. Categories are identified by the internal ID that was assigned by the Content Delivery Server.
`categoryList`	`Vector`, elements of type category	List of categories.
`city`	`String`	City for the subscriber's address.
`codedTicket`	`String`	String that identifies the purchase ticket for the download request.
`contactPhone`	`String`	Subscriber's phone number.
`content`	`Hashtable`	Container for the information about an item of content. This container includes the following items: contentId name shortDescription longDescription submitDate sizeInKB version contentType mimeType numberOfDownloads smallIconUrl largeIconUrl userGuideUrl previewUrl screenShot1Url screenShot2Url developerName developerUrl downloadTimes networks downloadUrl isBookmarked isPurchaseRequiredBeforeDownload isUnsubscribeAvailable isValidOnCurrentModel pricingDetails isActive
`contentBinary`	String	Binary format of content.
`contentCount`	`Integer`	Number of items of content in the category.
`contentId`	`Integer`	Internal ID that was assigned by the Content Delivery Server to the item of content with which you are working.
`contentIdList`	`Vector`, elements of type contentId	List of content IDs.
`contentKeyword`	`String`	Keyword used to identify content, typically used for content delivered directly to a device using SMS.
`contentLength`	`Integer`	Size of the content.
`contentList`	`Vector`, elements of type contentSummary	List of items of content.
`contentSummary`	`Hashtable`	Container for summary information about an item of content. This container includes the following items: contentId name shortDescription submitDate
`contentType`	`String`	Type of content with which you are working. This type must be one of the content types defined in the contentTypeList.
`contentTypeIdList`	`Vector`, elements of type Integer	List of content type IDs. Content types are identified by the internal ID that was assigned by the Content Delivery Server.
`contentTypeList`	`Vector`, elements of type Hashtable	Information about each content type defined in the Content Delivery Server. Each element contains the following items: id name
`country`	`Hashtable`	Container for information about a country. This container includes the following items: countryCode name
`countryCode`	`String`	Two-character ISO code that represents the subscriber's country, for example, `US`.
`countryList`	`Vector`, elements of type country	List of countries.
`couponCode`	`String`	String that identifies the coupon that the subscriber is using to purchase content.
`criteria`	`Hashtable`	Container for information about an item of content. This container includes the following items: filter campaignId (optional) bundleId (only if the content is part of a bundle) isSkipTrial licenseType
`deliveryType`	`String`	Type of delivery used to deliver content. The following values are valid: `ems` - Enhanced Messaging System `nsm` - Nokia Smart Messaging `one_step_wap` - One-step WAP `two_step_wap` - Two-step WAP
`description`	`String`	Description of the object. Depending on the method called, this is the description of the category, the campaign, the device, or the locale.
`descriptorData`	`String`	Content descriptor binary code. When returned by the `downloadContent` method of `DownloadHandler`, this is the binary preview file.
`developerName`	`String`	Name of the developer who submitted content.
`developerUrl`	`String`	URL for the developer who submitted the content.
`devicePhone`	`String`	Phone number of subscriber's device.
`displayOrder`	`Integer`	Position of the category in the list of categories. 1 indicates the top of the list.
`downloadCount`	`Integer`	Number of downloads allowed per purchase.
`downloadPeriod`	`Integer`	Number of days of use allowed per purchase.
`downloadPrice`	`Double`	Price charged to download the content.
`downloadTimes`	`Vector`, elements of type `String`	Estimated time that it takes to download the content. Each element corresponds to an element in the networks object to indicate the estimated time that the download takes over the corresponding type of network.
`downloadUrl`	`String`	URL from which the content is downloaded.
`emailAddress`	`String`	Subscriber's email address.
`eventType`	`String`	Type of event with which you are working. Use `sms_request_for_content` to indicate that the event is a request for information about an item of content.
`filter`	`Hashtable`	Container for Boolean flags that indicate the type of information to return. Information of the type associated with each flag is returned only if the flag is included in the hash table and is set to `true`. The following flags are valid when working with `ContentHandler`: `filterDetailsDownload` - Download information `filterDetailsDownloadCount` - Download count `filterDetailsIsBookmarked` - Information on bookmarks `filterDetailsResourceURLs` - Resource URLs `filterDetailsPricingAndPurchase` - Pricing and purchase information `filterDetailsPricingAndGifting` - Pricing information for gifts `filterDetailsIsValidOnCurrentModel` - Information on whether or not the content executes on the device The following flags are valid when working with `GiftHandler`: `filterGiftsContent` - Information about the content `filterGiftsDownload` - Download information
`firstName`	`String`	Subscriber's first name.
`gender`	`String`	Subscriber's gender. Valid values and what each value indicates are described in the following list: `M` - Subscriber is male. `F` - Subscriber is female.
`giftCost`	`Double`	Price of the gift.
`giftedDownloads`	`Integer`	Number of downloads that are paid for by the gift.
`giftedSubscriptions`	`Integer`	Number of subscriptions that are paid for by the gift.
`gifterId`	`Integer`	Subscriber ID for the subscriber who purchased the gift.
`gifterMobileId`	`String`	Mobile ID for the subscriber who purchased the gift.
`giftExpirationDate`	`Date`	Date that the gift expires.
`giftId`	`Integer`	Internal ID that is assigned by the Content Delivery Server to the gift with which you are working.
`gifting`	`Hashtable`	Container for information about a gift. This container contains the following items: giftId giftStatus giftIsOnDevice contentId giftTicket gifterId gifterMobileId giftRecipientId giftRecipientMobileId giftRecipientModelId message giftedDownloads giftedSubscriptions giftCost giftPurchaseDate giftExpirationDate pricingDetails
`giftIsOnDevice`	`Boolean`	Flag that indicates if the content provided by the gift exists on the target device. `True` indicates that the content is on the device. `False` indicates that the content is not on the device.
`giftingList`	`Vector`, elements of type gifting	List of gifts.
`giftPurchaseDate`	`Date`	Date that the gift was purchased.
`giftRecipientId`	`Integer`	Subscriber ID for the subscriber who is the recipient of a gift.
`giftRecipientMobileId`	`String`	Mobile ID for the subscriber who is the recipient of a gift.
`giftRecipientModelId`	`Integer`	Model ID of the device for the subscriber who is the recipient of a gift
`giftStatus`	Integer	Status of a gift. Valid values and what each value indicates are described in the following list: `8` - Gift is purchased `9` - Recipient has started downloading the gift `10` - Gift was successfully downloaded `11` - Gift is expired `12` - Gift is cancelled `13` - Gift is refunded
`giftTicket`	`String`	Internal object used to validate that the subscriber can access the gift.
`hasPurchases`	`Boolean`	Flag that indicates if a subscriber has purchased content. `True` indicates that the subscriber has purchased content. `False` indicates that the subscriber has not purchased content.
`id`	`Integer`	Internal ID that was assigned by the Content Delivery Server to the locale, or the content type, that you are working with.
`includeContentCount`	Boolean	Flag that indicates if the number of items in a category is calculated. `True` indicates that the number is calculated. `False` indicates that the number is be calculated.
`isActive`	`Boolean`	When included in the category object, this flag indicates if the category is shown to the subscriber. `True` indicates that the category is shown. `False` indicates that the category is not shown. When included in the content object, this flag indicates if the content is active. `True` indicates that the content is active. `False` indicates that the content is inactive.
`isAnonymous`	`Boolean`	Flag that indicates if the subscriber is anonymous. `True` indicates that the subscriber is anonymous. `False` indicates that the subscriber is known.
i`sBookmarked`	`Boolean`	Flag that indicates if the subscriber has bookmarked the content. `True` indicates that content is bookmarked. `False` indicates that the content is not bookmarked.
`isCategoryCustomized`	Boolean	Flag that indicates if the subscriber has customized the categories that are shown. `True` indicates that the categories are customized. `False` indicates that the categories are not customized.
`isContentInCampaign`	`Boolean`	Flag that indicates if the item of content is included in a campaign. `True` indicates that the item is in the campaign. `False` indicates that the item is not in the campaign.
`isDefault`	`Boolean`	Flag that indicates if the device is the default device. `True` indicates that the device is the default device. `False` indicates that the device is not the default device.
`isDownloaded`	`Boolean`	Flag that indicates if content has been downloaded. `True` indicates that an item of content has been downloaded. `False` indicates that an item of content has not been downloaded.
`isDownloadRecurring`	`Boolean`	Flag that indicates if the subscriber is automatically charged for additional downloads after the number of purchased downloads is exceeded. `True` indicates that renewal is automatic. `False` indicates that the subscriber must manually purchase additional downloads.
`isFree`	`Boolean`	Flag that indicates if the content is free. `True` indicates that the content is free. `False` indicates that the content must be purchased.
`isGiftExpired`	`Boolean`	Flag that indicates if the gift is expired. `True` indicates that the gift is expired and can no longer be claimed. `False` indicates that the gift is not expired.
`isGiftingUsed`	`Boolean`	Flag that indicates if all of the uses purchased for the gift were used by the recipient. `True` indicates that all of the uses that were purchased are used. `False` indicates that not all of the uses that were purchased are used.
`isLeafNode`	`Boolean`	Flag that indicates if the category has any subcategories. `True` indicates that the category does not have subcategories. `False` indicates that the category has subcategories.
`isMMSCapable`	`Boolean`	Flag that indicates if the content can be sent to the device using MMS. `True` indicates that MMS can be used. `False` indicates that MMS cannot be used.
`isOnDevice`	`Boolean`	Flag that indicates if an item of content is on a subscriber's device. `True` indicates that the item is on the device. `False` indicates that the item is not on the device.
`isOneStepConfirm`	`Boolean`	Flag that indicates if one-step or two-step download is used. `True` indicates that it is a one-step download. `False` indicates that it is a two-step download.
`isProvisioned`	`Boolean`	Flag that indicates if an entry for the subscriber exists in the Content Delivery Server database. `True` indicates that an entry does exist. `False` indicates that the subscriber is anonymous.
`isPurchaseRequiredBeforeDownload`	`Boolean`	Flag that indicates if the content must be purchased before being downloaded. `True` indicates that the content must be purchased first. `False` indicates that content can be downloaded.
`isPushEnabled`	`Boolean`	Flag that indicates if the device is push enabled. `True` indicates that the device is push enabled. `False` indicates that the device is not push enabled.
`isRegistered`	`Boolean`	Flag that indicates if the subscriber is registered in an external subscriber database. `True` indicates that the subscriber is registered. `False` indicates that the subscriber is not registered.
`isSkipTrial`	`Boolean`	Flag that indicates if the subscriber chooses to skip the trial usage. `True` indicates that the subscriber chooses to skip the trial usage so the content can be purchased immediately. `False` indicates that the subscriber chooses not to skip the trial usage.
`isSMSCapable`	`Boolean`	Flag that indicates if the content can be sent to the device using SMS. `True` indicates that SMS can be used. `False` indicates that SMS cannot be used.
`isSubscriptionExpired`	`Boolean`	Flag that indicates if the subscription has expired. `True` indicates that the subscription is expired. `False` indicates that the subscription is not expired.
`isSubscriptionRecurring`	`Boolean`	Flag that indicates if the subscription is automatically renewed. `True` indicates that renewal is automatic. `False` indicates that the subscriber must manually renew the subscription.
`isTicketValid`	`Boolean`	Flag that indicates if the subscriber can use the ticket to get an item of content. `True` indicates that the subscriber can use the ticket. `False` indicates that the subscriber cannot use the ticket.
`isTrialAvailable`	`Boolean`	Flag that indicates if the content can be used on a trial basis. `True` indicates that a trial is available. `False` indicates that no trial is available.
`isUpdateAvailable`	`Boolean`	Flag that indicates an update is available for the content. `True` indicates that an update is available. `False` indicates that an update is not available.
`isUnsubscribeAvailable`	`Boolean`	Flag that indicates if a subscription for the content can be canceled. `True` indicates that the subscription can be canceled. `False` indicates that there is no subscription or that the subscription cannot be canceled.
`isUsageConsumed`	`Boolean`	Flag that indicates if a subscriber has used the content for the number of uses purchased. `True` indicates that all purchased uses are used. `False` indicates that not all purchased uses are used.
`isValidOnCurrentModel`	`Boolean`	Flag that indicates if the content can be run on the model that the subscriber is using. `True` indicates that the content does run on the model. `False` indicates that the content does not run on the model.
`keyword`	`String`	String to match when searching for content.
`languageCode`	`String`	Two-character ISO code that represents the subscriber's language, for example, `en`.
`largeIconUrl`	`String`	URL that points to the large icon for the content.
`lastName`	`String`	Subscriber's last name.
`licenseType`	`Integer`	Type of license associated with the content. Valid values and what each value indicates are described in the following list: `0` - Content was purchased. `1` - Content was sent as a gift. `2` - Content was received as a gift.
`listEnd`	`String`	Together with `listStart`, specifies the range of items to return. The alphabetized list ends with items that match the string specified. The string is case sensitive. Specify null to end at the end of the complete list.
`listStart`	`String`	Together with `listEnd`, specifies the range of items to return. The alphabetized list begins with items that match the string specified. The string is case sensitive. Specify null to start at the beginning of the complete list.
`locale`	`Hashtable`	Container for locale information. This container contains the following items: id countryCode languageCode localeCode description
`localeCode`	`String`	String that represents the subscriber's locale, for example, `en_US`.
`localeList`	`Vector`, elements of type locale	List of locales.
`longDescription`	`String`	Long description from the information about the content
`manufacturer`	`String`	Name of the manufacturer of a device.
`manufacturerList`	`Vector`, elements of type manufacturer	List of manufacturers, sorted alphabetically.
`maxNumberToSend`	`Integer`	Maximum number of items to deliver in a call. If more items exist than the number specified, no content is sent. To deliver all items, use `-1`.
`message`	`String`	Message to be sent to a subscriber.
`messageCategory`	`Integer`	Category of message to be sent. Categories one through seven are sent to the subscriber, category 9 is sent to the Catalog Manager administrator. Valid values and what each value indicates are described in the following list: `1` - Message contains a URL that points to the details about an item of content. `2` - Message is a mobile originated message that contains a URL that points to the details about an item of content. `3` - Message contains the content binary. `4` - Message contains a gift and includes a URL that points to the details about an item of content. `5` - Message contains a notification and includes a URL that points to the details about an item of content. `6` - Message contains a password reminder. `7` - Message contains information about a campaign. `9` - New device was added to the Content Delivery Server.
`messageType`	`Integer`	Type of message to send. Valid values and what each value indicates are described in the following list: `1` - Message is sent to the subscriber's device. `2` - Message is sent to the subscriber's email.
`middleName`	`String`	Subscriber's middle name.
`mimeType`	`String`	MIME type of the content.
`mobileId`	`String`	Phone number for the subscriber.
`model`	`Hashtable`	Container for device information. This container includes the following items: modelId name description modelNumber manufacturer userAgentPattern isDefault
`modelId`	`Integer`	Internal ID that was assigned by the Content Delivery Server to the device that you are working with.
`modelList`	`Vector`, elements of type model	List of devices.
`modelNumber`	`String`	Model number associated with a device.
`name`	`String`	Name of the object. Depending on the method, this is the name of the category, the country, the campaign, the device, or the content.
`networks`	`Vector`, elements of type String	List of network types that are known by the Content Delivery Server. Each element corresponds to an element in the downloadTimes Vector to indicate the estimated time that the download takes for the corresponding network.
`notifyPromotions`	`Boolean`	Indicates if the subscriber wants to be notified about promotions. `True` indicates that the subscriber wants to be notified. `False` indicates that the subscriber does not want to be notified.
`numberOfDownloads`	`Integer`	Total number of times that the content was downloaded by all subscribers.
`numberToReturn`	`Integer`	Number of items to return in a list. To return all items, specify `-1`.
`parentCategoryId`	`Integer`	Internal ID that was assigned by the Content Delivery Server to the category that is the parent of the category that you are working with.
`password`	`String`	Unencrypted password for the subscriber. Encryption is performed by the Content Delivery Server.
`passwordRequiresReset`	`Boolean`	Flag that indicates if the subscriber's password must be reset when the subscriber logs in. `True` indicates that the password must be reset. `False` indicates that the password does not need to be reset.
`postalCode`	`String`	Postal code or ZIP code for a subscriber's address.
`preferenceList`	`Hashtable`	Container for a subscriber's preferences. This container includes items of type notifyPromotions. To delete a preference, set the value to the empty string (`').
`previewUrl`	`String`	URL that points to the preview file for the content.
`pricingDetails`	`Hashtable`	Container for pricing information for an item of content. This container includes the following items: campaignDiscount downloadPrice downloadCount downloadPeriod isDownloadRecurring subscriptionPrice subscriptionFrequency isSubscriptionRecurring trialCount usagePrice usageCount isFree isTrialAvailable
`propertyList`	`Vector`, elements are of type `Hashtable`	Information about each subscriber. Each element contains the following items: salutation firstName middleName lastName gender emailAddress addressLine1 addressLine2 city stateProvince postalCode countryCode contactPhone devicePhone
`propertyMap`	`Hashtable`	Set of name-value pairs used to configure system behavior. These values are internal values used by the Content Delivery Server.
`purchaseDate`	`Date`	Date the subscriber purchased the item.
`purchaseList`	`Vector`, elements are of type `Hashtable`	Information about each item purchased by the subscriber. Each element contains the following items: contentId name purchaseDate subscriptionExpiration pricingDetails isValidOnCurrentModel isSubscriptionExpired isUsageConsumed isUpdateAvailable isDownloaded isOnDevice codedTicket
`recipientApiContext`	`Hashtable`	Container for the information about the recipient of a gift. This container includes the following items: subscriberId username localeCode mobileId uniqueId modelId
`requestHeaders`	`Hashtable`	Container for the HTTP headers associated with an HTTP request.
r`equestParams`	`Hashtable`	Container for key-value pairs that provide information about an event. The following keys must be included: `request_data` - Data included in the request, such as the unparsed SMS request for content or for a campaign `request_source` - Source of the request, such as the short code to which it is sent `request_type` - String that identifies the type of request, such as `portal` or `mo_push` or other value recognized by your system Additional keys that your system recognizes can also be included.
`response_code`	`String`	Code that indicates if the method executed successfully. `1` indicates successful completion. `-1` indicates an error occurred.
`response_message`	`String`	Message returned by the method.
`roleId`	`Integer`	Role assigned to the subscriber. Valid values and what each value indicates are described in the following list: `0` - Subscriber has access only to content with a status of `Testing`. `1` - Subscriber has standard privileges.
`salutation`	`String`	Courtesy title, such as Mr.
`screenShot1Url`	`String`	URL that points to the first screen shot for the content.
`screenShot2Url`	`String`	URL that points to the second screen shot for the content.
`searchFilter`	`Hashtable`	Container for the criteria used to filter the results of a content search. This container includes the following items: categoryId developerName keyword The container must include at least one type of criterion.
`shortDescription`	`String`	Short description from the information about the content.
`sizeInKB`	`String`	Size of content.
`smallIconUrl`	`String`	URL that points to the small icon for the content.
`smsParams`	`Hashtable`	Container for parameters required to push binary content to a device. The entries in the hash table are pairs of strings that identify the name and value of each parameter needed.
`startIndex`	`Integer`	The position in a list of items at which to begin processing.
`stateProvince`	`String`	State or province for the subscriber's address.
`status`	`String`	Confirm status string returned by the device. For possible values returned by MIDP applications, see `http://www.jcp.org/jsr/detail/118.jsp`.
`statusList`	`Vector`, elements of type `Integer`	List of content statuses. Valid values and what each value indicates are described in the following list: `1` - Content is active. Content is stocked and available to the subscriber. `2` - Content is inactive. Content is stocked, but not available to the subscriber. `3` - Content is unavailable. Content is no longer available from the Catalog Manager. `4` - Content is being tested and is available only to subscribers who are assigned the role of tester.
`subCategoryList`	`Vector`, elements of type category	List of categories under a specified node.
`subject`	`String`	Subject of the message to be sent to a subscriber.
`submitDate`	`Date`	Date the content was submitted.
`subscriberId`	`Integer`	Internal ID that was assigned by the Content Delivery Server to the subscriber account.
`subscriptionExpiration`	`Date`	Date the subscriber's subscription expires.
`subscriptionFrequency`	`String`	Period of time covered by a subscription. Valid values are `daily`, `weekly`, `monthly`, and `yearly`.
`subscriptionPrice`	`Double`	Price charged for a subscription for the content.
`ticket`	`String`	Internal object used to validate that the subscriber can access the content requested.
`totalSize`	`Integer`	Number of items found.
`trialCount`	`Integer`	Number of times the content can be used for free before the subscriber is prompted to purchase.
`uniqueId`	`String`	Unique ID for the subscriber.
`url`	`String`	URL to include in a message sent to a subscriber.
`usageCount`	`Integer`	Number of uses allowed per purchase.
`usagePrice`	`Double`	Price charged per use or number of uses.
`userAgent`	`String`	User agent for a device. This string is the exact string that was returned in the HTTP header.
`userAgentPattern`	`String`	User agent for a device. This string is a regular expression, which is a pattern that can match various text strings.
`userGuideUrl`	`String`	URL that points to the User Guide for the content.
`username`	`String`	User name for the subscriber.
`version`	`String`	The version of the content.
`wasDelivered`	`Boolean`	Flag that indicates that the content was sent to the device using SMS. `True` indicates that SMS was used. `False` indicates that SMS was not used.

10.3.3 Examples of Using Handlers

This section presents two examples of using the XML-RPC implementation of the Subscriber API.

10.3.3.1 Example of Creating an `ApiContext` Object

The following code excerpt shows how to create an ApiContext Object. This sample uses the bindings for the Java programming language.

CODE EXAMPLE 10-3 Create an `APIContext` Object Using XML-RPC
... // Get a reference to the XmlRpcClient String url = "http://host1:8080/subscriber/xml_rpc.do"; XmlRpcClientLite client = new XmlRpcClientLite(url); // Set up the input parameters Vector parameters = new Vector(); Hashtable ht = new Hashtable(); ht.put("username", "user1"); ht.put("password", "cryptic1"); parameters.addElement(ht); // Send the request to Content Delivery Server Hashtable response = (Hashtable) client.execute("AuthenticationHandler.getApiContext", parameters); // Evaluate the response String errorCode = (String)response.get("response_code"); if (!errorCode.equals("1")) { // Handle Error System.out.println((String)response.get("response_message")); ... } else { // Authentication successful Hashtable apiContext = (Hashtable)response.get("apiContext"); Integer subscriberId = (Integer)apiContext.get("subscriberId"); String username = (String)apiContext.get("username"); String localeCode = (String)apiContext.get("localeCode"); String mobileId = (String)apiContext.get("mobileId"); Integer modelId = (Integer)apiContext.get("modelId"); ... // Save the ApiContext Hashtable in the Session session.setAttribute("API_CONTEXT", apiContext); ... } ...

CODE EXAMPLE 10-3 Create an APIContext Object Using XML-RPC

...

// Get a reference to the XmlRpcClient

String url = "http://host1:8080/subscriber/xml_rpc.do";

XmlRpcClientLite client = new XmlRpcClientLite(url);

// Set up the input parameters

Vector parameters = new Vector();

Hashtable ht = new Hashtable();

ht.put("username", "user1");

ht.put("password", "cryptic1");

parameters.addElement(ht);

// Send the request to Content Delivery Server

Hashtable response =

(Hashtable) client.execute("AuthenticationHandler.getApiContext", parameters);

// Evaluate the response

String errorCode = (String)response.get("response_code");

if (!errorCode.equals("1"))

  // Handle Error

  System.out.println((String)response.get("response_message"));

...

else

  // Authentication successful

  Hashtable apiContext = (Hashtable)response.get("apiContext");

  Integer subscriberId = (Integer)apiContext.get("subscriberId");

  String username = (String)apiContext.get("username");

  String localeCode = (String)apiContext.get("localeCode");

  String mobileId = (String)apiContext.get("mobileId");

  Integer modelId = (Integer)apiContext.get("modelId");

...

  // Save the ApiContext Hashtable in the Session

  session.setAttribute("API_CONTEXT", apiContext);

...

...

10.3.3.2 Example of Creating a Handler and Purchasing Content

The following code excerpt shows how to create a handler and use that handler to purchase content. This sample uses the bindings for the Java programming language.

CODE EXAMPLE 10-4 Create a Handler
... // Get a reference to the XmlRpcClient String url = "http://[[cds server host]]:[[cds server port]]/subscriber/xml_rpc.do"; XmlRpcClientLite client = new XmlRpcClientLite(url); // Retrieve the ApiContext Hashtable from the HttpSession Hashtable apiContext = (Hashtable) session.getAttribute("API_CONTEXT"); // Set up the input parameters Vector parameters = new Vector(); Hashtable ht = new Hashtable(); ht.put("apiContext", apiContext); ht.put("contentId", new Integer(1001)); ht.put("campaignId", new Integer(1000)); ht.put("isSkipTrial", Boolean.TRUE); parameters.addElement(ht); // Send the request to Content Delivery Server Hashtable response = (Hashtable) client.execute("ContentHandler.purchaseContent", parameters); // Evaluate the response String errorCode = (String)response.get("response_code"); if (!errorCode.equals("1")) { // Handle Error System.out.println((String)response.get("response_message")); ... } else { // Purchase successful ... } ...

CODE EXAMPLE 10-4 Create a Handler

...

// Get a reference to the XmlRpcClient

String url = "http://[[cds server host]]:[[cds server port]]/subscriber/xml_rpc.do";

XmlRpcClientLite client = new XmlRpcClientLite(url);

// Retrieve the ApiContext Hashtable from the HttpSession

Hashtable apiContext = (Hashtable) session.getAttribute("API_CONTEXT");

// Set up the input parameters

Vector parameters = new Vector();

Hashtable ht = new Hashtable();

ht.put("apiContext", apiContext);

ht.put("contentId", new Integer(1001));

ht.put("campaignId", new Integer(1000));

ht.put("isSkipTrial", Boolean.TRUE);

parameters.addElement(ht);

// Send the request to Content Delivery Server

Hashtable response =

(Hashtable) client.execute("ContentHandler.purchaseContent", parameters);

// Evaluate the response

String errorCode = (String)response.get("response_code");

if (!errorCode.equals("1"))

  // Handle Error

  System.out.println((String)response.get("response_message"));

...

else

  // Purchase successful

...

...

10.1 General Process Flow

10.2 Using the Subscriber API

10.2.1 Managing Transactions

10.2.2 Example of Creating an IApiContext Object

10.2.3 Example of Creating a Service

10.3 XML-RPC Implementation

10.3.1 Accessing the Content Delivery Server

10.3.2 Using XML-RPC Handlers for the Subscriber API

10.3.2.1 Guidelines for Calls to XML-RPC Methods

10.3.2.2 AuthenticationHandler

10.3.2.3 CategoryHandler

10.3.2.4 ContentHandler

10.3.2.5 DownloadHandler

10.3.2.6 GiftingHandler

10.3.2.7 MessageHandler

10.3.2.8 SystemHandler

10.3.2.9 UserHandler