Subscriber API

C H A P T E R 11

Subscriber API

The Subscriber API provides access to data maintained by 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 Content Delivery Server.

Clients that are written in the Java programming language and located on a server with the Subscriber Portal component of Content Delivery Server can call the Subscriber API directly. Clients written in a programming 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, as well as accessing preview files.

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.

IStreamingService - Interface that provides Content Delivery Server with access to streamed content and enables the streaming server to authenticate requests for content.

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/cdsapi/index.html.

11.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 11.3, XML-RPC Implementation for the equivalent handler if you are accessing Content Delivery Server data using XML-RPC.

An authentication key is used to authenticate requests for access to Content Delivery Server. This key is included in the IApiContext object and is generated when an IApiContext object is created. An authentication key is required to create a service and expires if not used within a set number of minutes. The default period is 10 minutes. To change the period, set the subscriberApi.authkey.timeout.minutes property in the $CDS_HOME/deployment/deployment-name/conf/SubscriberPortal.properties file. If the key expires, you must create a new IApiContext object to get a new key.

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 the authentication key in the HttpSession object. To get the authentication key, call the IApiContext.getAuthKey method. See Section 11.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 authentication key to create a service. Each service created provides data specific to the subscriber described by the IApiContext object. See Section 11.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 the getCampaigns method to get the list of campaigns available to the subscriber or the getPurchases method to get the list of items that the subscriber has already purchased.

Log off Content Delivery Server.

When you are done, remove the authentication key by calling the IApiContextFactory.removeApiContext method.

11.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/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.

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 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 11.3, XML-RPC Implementation for information on accessing the Subscriber API through XML-RPC.

11.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 Content Delivery Server as described in the following steps:

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

2. If the transaction completes successfully, call the ApiUtil.commitTransaction method to commit the work done. If an error occurs during the transaction, call the ApiUtil.rollbackTransaction method 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 the ApiUtil.disposeTransaction method.

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

11.2.2 Example of Creating an `IApiContext` Object

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

CODE EXAMPLE 11-1 Create an `IApiContext` Object Using Java Class Files
... 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 authentication key in the HttpSession session.setAttribute("API_CONTEXT_AUTH_KEY", apiContext.getAuthKey()); // 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 11-1 Create an IApiContext Object Using Java Class Files

...
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 authentication key in the HttpSession
  session.setAttribute("API_CONTEXT_AUTH_KEY", apiContext.getAuthKey());
 
  // 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();
}
...

11.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 11-2 Create a Service
... try { // Open a Transaction ApiUtil.initTransaction(); // Retrieve the IApiContext authentication key from the HttpSession String apiContextAuthKey = (String)session.getAttribute("API_CONTEXT_AUTH_KEY"); // Get a reference to a Content Service IContentService cs = ApiServiceFactory.getContentService(apiContextAuthKey); // 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 11-2 Create a Service

...
try
{
  // Open a Transaction
  ApiUtil.initTransaction();
 
  // Retrieve the IApiContext authentication key from the HttpSession
  String apiContextAuthKey = 
      (String)session.getAttribute("API_CONTEXT_AUTH_KEY");
 
  // Get a reference to a Content Service
  IContentService cs = ApiServiceFactory.getContentService(apiContextAuthKey);
 
  // 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();
}
...

11.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 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.

11.3.1 Accessing Content Delivery Server

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

In addition, 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 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

11.3.2 Using XML-RPC Handlers for the Subscriber API

The general flow of your application (see Section 11.1, General Process Flow) is similar whether you access the Subscriber API directly or through XML-RPC. In both cases, an API Context object is required to access services. When accessing the Subscriber API directly, the authentication key is used to create services. When using XML-RPC, the AuthenticationHandler is used to get an API Context object, which is passed in to every method.

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

StreamingHandler

SystemHandler

UserHandler

Parameters for the Methods

11.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 11.3.3, Examples of Using Handlers.

11.3.2.2 `AuthenticationHandler`

AuthenticationHandler is equivalent to the ApiContextFactory class. This handler creates the API Context object that contains the characteristics of the subscriber. The API Context object is equivalent to the IApiContext object. The guidelines for calling a method in a handler are described in Section 11.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 11-1 Methods for `AuthenticationHandler`
Method Name	Description	Parameters	Returns^{^[1]}
`getAnonymousApiContext`	Creates an API Context object for an anonymous subscriber.	localeCode, modelId	apiContext
`getApiContext`	Authenticates the subscriber based on the information provided and create an API Context object that contains the information for that subscriber.	One of the following items: username and password mobileId uniqueId subscriberId requestHeaders	apiContext

11.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 11.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 11-2 Methods for `CategoryHandler`
Method Name	Description	Parameters	Returns ^[2]
`getCategory`	Gets the specified category for the current subscriber.	apiContext, categoryId, includeContentCount	category
`getCategoryBranch`	Gets an entire branch of the category tree beginning with the category specified in `categoryId`. To get the entire tree, specify the root category. The categories returned 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 (option), statusList (optional), includeContentCount	category
`getNotEmptySubCategories`	For the category specified in `categoryId`, gets 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`, gets the list of all subcategories.	apiContext, categoryId, includeContentCount	categoryList
`getRootCategory`	Gets the root category for the current subscriber.	apiContext, includeContentCount	category
`hideCategory`^{^[3]}	Hides the categories specified in `categoryIds` that the subscriber has chosen to not view and return the updated list.	apiContext, categoryIds, categoryList	categoryList
`moveCategoryDown`^*	Moves each category specified in `categoryIds` down one position below the next active category and return the updated list.	apiContext, categoryIds, categoryList	categoryList
`moveCategoryUp`^*	Moves each category specified in `categoryIds` up one position above the next active category and return the updated list.	apiContext, categoryIds, categoryList	categoryList
`showCategory`*	Shows the categories specified in `categoryIds` that the subscriber has selected and return the updated list.	apiContext, categoryIds, categoryList	categoryList
`updateCategories`	Updates the information in the database for the categories in `categoryList`.	apiContext, categoryList	None

11.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 11.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 11-3 Methods for `ContentHandler`
Method Name	Description	Parameters	Returns^{^[4]}
`addBookmark`	Adds an item of content to the subscriber’s list of bookmarked content.	apiContext, contentId	None
`browseContent`	Gets 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. Note - This method is deprecated. Use the new version of the searchContent method.	apiContext, categoryId, contentTypeIdList (optional), startIndex, numberToReturn	contentList, totalSize
`cancelSubscription`	Cancels the subscriber’s subscription to an item of content.	apiContext, contentId	None
`clearBookmarks`	Clears a subscriber’s list of bookmarked content.	apiContext	None
`deleteBookmark`	Deletes an item of content from the subscriber’s list of bookmarked content.	apiContext, contentId	None
`getAnonymousCampaignForCoupon`	Gets the information for a campaign that is associated with the coupon specified. Call this method if the subscriber is anonymous.	apiContext, couponCode	campaign
`getBookmarks`	Gets the list of items the subscriber has bookmarked.	apiContext	contentList
`getBundledItems`	Gets the items of content in a bundle.	apiContext, contentId, criteria	contentList, totalSize
`getCampaign`	Gets the information for a campaign.	apiContext, campaignId	campaign
`getCampaignForCoupon`	Gets the information for a campaign that is associated with the coupon specified. Call this method if the subscriber is known.	apiContext, couponCode	campaign
`getCampaignItems`	Gets the list of content associated with the campaign.	apiContext, campaignId, startIndex, numberToReturn	contentList, totalSize
`getCampaigns`	Gets the list of campaigns that are available to the subscriber.	apiContext	campaignList
`getContentByClassId`	Gets the content ID for a specific edition of the content identified by `contentClassId`.	apiContext, contentClassId	contentId
`getContentByKeyword`	Gets the content ID for a specific edition of the content identified by `contentKeyword`.	apiContext, contentKeyword	contentId
`getContentDetails`	Gets the information about an item of content.	apiContext, contentId, criteria	content
`getContentDetailsCriteria`	Gets an empty criteria object, which can be used for methods that accept criteria as a parameter.	apiContext	criteria
`getContentDetailsList`	Gets the information for each item of content specified in `contentIdList`.	apiContext, contentId, criteria	contentList
`getContentSummary`	Gets summary information for an item of content.	apiContext, contentId	contentSummary
`getDeliveryType`	Gets the type of delivery used to deliver this content.	apiContext, contentId	deliveryType
`getPurchasedBundles`	Gets the list of bundles purchased by the subscriber that contain the item of content specified in `contentId`.	apiContext, contentId	contentList, totalSize
`getPurchases`	Gets the list of content that the subscriber has purchased.	apiContext	purchaseList
`getSupportedModels`	Gets the list of models on which the content can run.	apiContext, contentId	modelList
`getTicket`	Gets the purchase ticket for the content identified by `contentId`.	apiContext, contentId, bundleId (specify only if content is part of a bundle)	codedTicket
`hasPurchases`	Determines if the subscriber purchased any content.	apiContext	hasPurchases
`isBookmarked`	Determines if the subscriber bookmarked the content.	apiContext, contentId	isBookmarked
`isContentInCampaign`	Determines if the content specified in `contentId` is in the campaign specified in `campaignId`.	apiContext, contentId, campaignId	isContentInCampaign
`isMMSCapable`	Determines if the content can be pushed to the device using MMS.	apiContext, contentId	isMMSCapable
`isSMSCapable`	Determines if the content can be pushed to the device using SMS.	apiContext, contentId	isSMSCapable
`purchaseContent`	Purchases content. If `campaignID` is specified, purchases content that is part of a campaign. Not available for anonymous subscribers.	apiContext, contentId, campaignId (optional), isSkipTrial	None
`requestContent`	Sends content to a subscriber. Content must first be purchased.	apiContext, contentId, requestParams, maxNumberToSend	wasDelivered
`searchContent`	Gets the list of content summaries for content that matches the search query.	apiContext, searchQuery, sortKeyMap, categoryId, startIndex, numberToReturn	contentList, totalSize
`searchContent`	Gets 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`.) Note - This method is deprecated. Use the new version.	apiContext, categoryId, contentTypeIdList (optional), keyword, startIndex, numberToReturn	contentList, totalSize

11.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 11.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 11-4 Methods for `DownloadHandler`
Method Name	Description	Parameters	Returns^{^[5]}
`downloadConfirm`	Confirms that the content was downloaded to the device.	apiContext, codedTicket, isOneStepConfirm, status	None
`downloadContent`	Downloads the binary file for the item of content specified by `contentId`.	apiContext, contentId	contentLength, contentType, descriptorData
`downloadContentDescriptor`	Creates a content descriptor file and return it to the caller.	apiContext, codedTicket	contentLength, contentType, descriptorData
`downloadDelete`	Confirms that the content was deleted from the device.	apiContext, codedTicket, isOneStepConfirm, status	None
`downloadJAD`	Creates a Java Application Descriptor (JAD) file and return it to the caller.	apiContext, codedTicket	contentLength, contentType, descriptorData
`downloadJAM`	Creates an application descriptor file for an iAppli application and return it to the caller.	apiContext, codedTicket	contentLength, contentType, descriptorData
`pushMMSContent`	Pushes content to the device using MMS. Note - This method is deprecated. Use the `pushMMSContentByTicket` method.	apiContext, contentId	None
`pushMMSContentByTicket`	Pushes content identified by `codedTicket` to the device using MMS.	apiContext, codedTicket	None
`pushSMSContentBinary`	Pushes external content to the device using SMS.	apiContext, mobileId, contentBinary, mimeType, contentType, smsParams	None
`pushSMSContentByTicket`	Pushes content identified by `codedTicket` to the device using SMS.	apiContext, codedTicket, smsParams	None
`sendInstall`	Pushes content installation file to a subscriber’s device.	apiContext, codedTicket	None

11.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 11.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 11-5 Methods for `GiftingHandler`
Method Name	Description	Parameters	Returns^{^[6]}
`cancelGifting`	Cancels a gift subscription.	apiContext, giftId	None
`checkAndExpireGifting`	Determines if the gift is expired.	apiContext, gifting	isGiftExpired
`getGiftingById`	Gets the information about the gift specified by `giftId`.	apiContext, giftId, filter, bundledContentId	gifting
`getGiftingByTicket`	Gets the information about the gift specified by `giftTicket`.	apiContext, giftTicket, filter, bundledContentId	gifting
`getGiftingsByGifter`	Gets the information for all of the gifts given by the subscriber.	apiContext, filter	giftingList
`getGiftingsByRecipient`	Gets the information for all of the gifts received by the subscriber.	apiContext, filter	giftingList
`giftContent`	Purchases an item of content as a gift for another subscriber.	apiContext, contentId, campaignId (optional), recipientApiContext, message, giftedDownloads, giftedSubscriptions	giftId
`isGiftingUsed`	Determines if the recipient claimed all of the uses provided by the gift.	apiContext, gifting	isGiftingUsed
`messageContent`	Sends a message about an item of content to another subscriber.	apiContext, contentId, recipientApiContext, message	giftId

11.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 11.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 11-6 Methods for `MessageHandler`
Method Name	Description	Parameters	Returns^{^[7]}
`sendMessageToMobileId`	Sends a message to the number specified by the mobile ID provided.	apiContext, subject, message, url, mobileId, contentId, messageCategory	None
`sendMessageToSelf`	Sends a message to the current subscriber.	apiContext, messageType, subject, message, url, contentId, messageCategory	None
`sendMessageToSubscriberId`	Sends a message to the subscriber identified by the subscriber ID provided.	apiContext, messageType, subject, message, url, subscriberId, contentId, messageCategory	None
`sendMessageToUsername`	Sends a message to the subscriber identified by the user name provided.	apiContext, messageType, subject, message, url, username, contentId, messageCategory	None
`sendMMSContent`	Sends content to the current subscriber using MMS push.	apiContext, mobileId, contentBinary, name, contentType, mimeType, subject, message, modelId, contentId, messageCategory	None

11.3.2.8 `StreamingHandler`

StreamingHandler is equivalent to the IStreamingService interface. This handler provides Content Delivery Server with information about a streaming session and enables the streaming server to validate requests for content. The guidelines for calling a method in a handler are described in Section 11.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:

StreamingHandler.authenticate

The following table describes the StreamingHandler methods.

TABLE 11-7 Methods for `StreamingHandler`
Method Name	Description	Parameters	Returns^{^[8]}
`authenticate`	Verifies that the subscriber who is requesting streamed content is known to Content Delivery Server.	apiContext	isAuthenticated
`authorize`	Verifies that the subscriber who is requesting streamed content has purchased the item requested.	apiContext, codedTicket	isAuthenticated
`endSession`	Notifies Content Delivery Server that a streaming session has ended.	apiContext, codedTicket	None
`errorInSession`	Notifies Content Delivery Server that an error occurred during a streaming session	apiContext, codedTicket	None
`startSession`	Notifies Content Delivery Server that a streaming session has started.	apiContext, codedTicket	None

11.3.2.9 `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 11.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 11-8 Methods for `SystemHandler`
Method Name	Description	Parameters	Returns^{^[9]}
`createTicket`	Creates a ticket for a subscriber to use to retrieve an item of content.	apiContext, contentId	ticket
`getContentTypes`	Gets a list of all of the content types that are defined in Content Delivery Server.	apiContext	contentTypeList
`getCountries`	Gets a list of all of the countries that are included in Content Delivery Server.	apiContext	countryList
`getCountry`	Gets the information for a single country.	apiContext, countryCode	country
`getDefaultLocale`	Gets the default locale for the system.	apiContext	locale
`getDefaultMode`l	Gets the default device model.	apiContext	modelId
`getLocale`	Gets the information for a single locale.	apiContext, localeCode	locale
`getLocales`	Gets a list of all of the locales included in Content Delivery Server.	apiContext	localeList
`getManufacturers`	Gets the names of all of the device manufacturers included in Content Delivery Server.	apiContext	manufacturerList
`getModel`	Gets the information for a device.	apiContext, modelId	model
`getModelId`	Gets the internal ID for the device associated with the user agent specified in `modelId`.	apiContext, userAgent	modelId
`getModels`	Gets a list of all of the devices supported by Content Delivery Server.	apiContext	modelList
`getModelsForManufacturer`	Gets the models in Content Delivery Server for a given manufacturer. Only models that are not quarantined are returned.	apiContext, manufacturer	modelList
`isPushEnabled`	Determines if the subscriber’s device is push enabled.	apiContext, modelId	isPushEnabled
`isTicketValid`	Determines if the ticket for an item of content can be used by the subscriber.	apiContext, ticket, contentId	isTicketValid
`sendEvent`	Sends 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`	Sends a system event with a set of event parameters.	apiContext, requestParams	None

11.3.2.10 `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 11.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 11-9 Methods for `UserHandler`
Method Name	Description	Parameters	Returns^{^[10]}
`disableSubscriberBySubscriberId`	Disables the account for the subscriber identified by the subscriber ID.	apiContext, subscriberId	None
`disableSubscriberByUsername`	Disables the account for the subscriber identified by the user name.	apiContext, username	None
`getSubscriberId`	Gets the subscriber ID for the subscriber identified by the user name.	apiContext, username	subscriberId
`getUserPreferences`	Gets the preferences set by the subscriber.	apiContext	preferenceList
`getUserProperties`	Gets the information for the current subscriber.	apiContext	propertyList
`getUserPropertiesBySubscriberId`	Gets the information for the subscriber identified by the subscriber ID.	apiContext, subscriberId	propertyList
`getUserPropertiesByUsername`	Gets the information for the subscriber identified by the user name.	apiContext, username	propertyList
`provision`	Populates a subscriber account in Content Delivery Server with information from an external subscriber database.	apiContext, uniqueId, modelId, mobileId, localeCode	subscriberId
`resetPasswordBySubscriberId`	Sets the password for the subscriber identified by the subscriber ID to a value generated by the system.	apiContext, subscriberId, passwordRequiresReset	password
`resetPasswordByUsername`	Sets the password for the subscriber identified by the user name to a value generated by the system.	apiContext, username, passwordRequiresReset	password
`setLocaleCode`	Changes the subscriber’s locale code.	apiContext, localeCode	None
`setModelId`	Changes the model ID to match the new device that the subscriber is using.	apiContext, modelId	None
`setPassword`	Changes the subscriber’s password.	apiContext, password	None
`setUserPreferences`	Sets the preferences selected by a subscriber. These preferences manage the information that is shown to the user.	apiContext, preferenceList	None
`setUserProperties`	Sets the information for a subscriber.	apiContext, propertyList	None
`signup`	Creates a subscriber account in Content Delivery Server and in any external subscriber database.	apiContext, username, password, modelId, mobileId, uniqueId, localeCode	subscriberId
`signupWithPropertiesAndPreferences`	Creates a subscriber account in 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

11.3.2.11 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 11-10 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 modelId uniqueId 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 Content Delivery Server to an individual item in a bundle.
`bundleId`	`Integer`	Internal ID that was assigned by 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 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 sortingQuery subCategoryList (only included if returned by the getCategoryBranch method of `CategoryHandler`)
`categoryId`	`Integer`	Internal ID that was assigned by 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 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 contentClassId name shortDescription longDescription submitDate sizeInKB version contentType isBundle isBundledItem mimeType numberOfDownloads smallIconUrl largeIconUrl userGuideUrl previewListMap customFieldCollection developerName developerUrl downloadTimes networks downloadUrl isBookmarked isPurchaseRequiredBeforeDownload isUnsubscribeAvailable isValidOnCurrentModel pricingDetails isActive
`contentBinary`	`String`	Binary format of content.
`contentClassId`	`Integer`	Unique identifier that identifies an item of content in the Catalog Manager. The class ID refers to an item and all of the editions associated with that item.
`contentCount`	`Integer`	Number of items of content in the category.
`contentId`	`Integer`	Internal ID that was assigned by 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`	List of items of content. When returned by the getContentDetailsList method of `ContentHandler`, the vector elements are of type content. When returned by other methods of `ContentHandler`, the vector elements are of type contentSummary.
`contentSummary`	`Hashtable`	Container for summary information about an item of content. This container includes the following items: contentId name contentType shortDescription submitDate contentClassId longDescription sizeInKB developerName contentKeyword isBundle
`contentType`	`String`	Type of content with which you are working. This type must be one of the content types defined in the contentTypeList. When returned by the methods of DownloadHandler, this is the MIME type of the binary data or descriptor.
`contentTypeIdList`	`Vector`, elements of type `Integer`	List of content type IDs. Content types are identified by the internal ID that was assigned by Content Delivery Server.
`contentTypeList`	`Vector`, elements of type `Hashtable`	Information about each content type defined in 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
`customField`	`Hashtable`	Container for information about a custom field that you defined for your installation of Content Delivery Server. This container includes the following items: customFieldId customFieldCustomKey customFieldNumber customFieldText customFieldTimestamp customFieldBoolean customFieldLabel customFieldDatatype customFieldScope
`customFieldBoolean`	`Boolean`	Value stored for custom field of type `boolean`.
`customFieldCollection`	`Vector`, elements of type customField	List of custom fields defined for your installation.
`customFieldCustomKey`	`String`	String used to identify the custom field to Content Delivery Server.
`customFieldDatatype`	`String`	Type of data stored in the custom field. Valid values are `boolean`, `number`, `text`, and `timestamp`.
`customFieldId`	`Integer`	Internal ID that was assigned by Content Delivery Server to identify the custom field.
`customFieldLabel`	`String`	String used in the user interface to identify the custom field.
`customFieldNumber`	`Double`	Value stored for custom field of type `number`.
`customFieldScope`	`String`	Identifies whether the field applies to the content item or to an edition of the content item.
`customFieldText`	`String`	Value stored for custom field of type `text`.
`customFieldTimestamp`	`Date`	Value stored for custom field of type `timestamp`.
`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`	`Array` of bytes	Binary form of the content descriptor as base64-encoded data. When returned by the `downloadContent` method of `DownloadHandler`, this is the content binary 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`: `filterDetailsResourceBinaries` - Binaries for preview files `filterDetailsDownload` - Download information `filterDetailsDownloadCount` - Download count `filterDetailsIsBookmarked` - Information on bookmarks `filterDetailsResourceURLs` - URLs for preview files `filterDetailsPricingAndPurchase` - Pricing and purchase information `filterDetailsPricingAndGifting` - Pricing information for gifts `filterDetailsIsValidOnCurrentModel` - Information on whether or not the content executes on the device `filterDetailsIncludeRetailPrice` - Retail price Note - If `filterDetailsResourceBinaries` is not specified in the filter, the binary of a preview file is not available in the preview object. An attempt to get the binary from the preview object returns null. If `filterDetailsResourceURLs` is not specified in the filter, the URL of a preview file is not available in the preview object. An attempt to get the URL from the preview object returns the empty string. If neither of these flags is included in the filter, previewListMap is null and no access to preview files is provided. 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 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 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.
`isAuthenticated`	`Boolean`	Flag that indicates if the person attempting to access streamed content is an authentic Content Delivery Server subscriber or that the subscriber has purchased the item requested.
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.
`isBundle`	`Boolean`	Flag that indicates if the item is a bundle. `True` indicates that the item is a bundle. `False` indicates that the item is not a bundle.
`isBundledItem`	`Boolean`	Flag that indicates if the item is included in a bundle. `True` indicates that the item is part of a bundle. `False` indicates that the item is not part of a bundle.
`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 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 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 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 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 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 (‘’).
`preview`	`Hashtable`	Container for information about a preview. This container includes the following items: previewBinary previewCaption previewLastModifiedDate previewMimeExtension previewMimeType previewPositionIndex previewTarget previewUrl
`previewBinary`	`Array` of bytes	Binary form of preview file as base64-encoded data.
`previewCaption`	`String`	String used to identify the preview. This string is optional and could be empty. If desired, your code can replace the empty string with the string of your choice.
`previewLastModifiedDate`	`Date`	Date when the preview file was last changed. If you are caching preview files, use this date to determine if the cache needs to be updated.
`previewListMap`	`Hashtable`	Container of preview files for both WAP previews and web previews. This container includes the following items: wapPreviews webPreviews If neither `filterDetailsResourceBinaries` nor `filterDetailsResourceURLs` is specified in the filter, this item is null. If one of the flags is specified and one of the targets has no preview files, the list for that target is empty.
`previewMimeExtension`	`String`	Extension of the original preview file, for example, `.jpg`.
`previewMimeType`	`String`	MIME type of the preview file, for example, `image/jpg`.
`previewPositionIndex`	`Integer`	Position of the file in the preview set. The position index of the first file in the preview set is `1`.
`previewTarget`	`Integer`	Type of browser for which the preview file is targeted. Valid values and what each value indicates are described in the following list: `0` - Target is WAP browsers. `1` - Target is web browsers.
`previewUrl`	`String`	URL that points to the preview file.
`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 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.
`score`	`Double`	Value that indicates how relevant the item found is to the search query. High numbers indicate high relevancy. Valid values are `0.0` to `1.0`. The default is `0.5`.
`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.
`searchQuery`	`String`	Any valid search query as defined by the Search Query Expression Language used by the Apache Lucene project. See `http://lucene.apache.org/java/docs/queryparsersyntax.html` for additional information.
`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.
s`ortingQuery`	String	Attribute by which results from a query are sorted. This is the value set by the Vending Manager administrator for a category. If no value is set for the category, the query sort value for the closest parent category is used. If no parent category has a query sort value specified, `null` is used.
`sortKeyMap`	`Hashtable`	Container for the fields by which search results are sorted. The entries in the hash map are `String` and `Boolean` pairs where the string is the name of the field on which to sort and the boolean indicates whether to sort in ascending or descending order. A value of `true` indicates ascending order, `false` indicates descending order.
`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 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.
`wapPreviews`	`Vector`, elements of type preview	List of preview files targeted for WAP browsers. If no preview files are targeted for WAP browsers, an empty list is returned.
`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.
`webPreviews`	`Vector`, elements of type preview	List of preview files targeted for web browsers. If no preview files are targeted for web browsers, an empty list is returned.

11.3.3 Examples of Using Handlers

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

11.3.3.1 Example of Creating an API Context Object

The following code excerpt shows how to create an API Context object. This sample uses the bindings for the Java programming language.

CODE EXAMPLE 11-3 Create an API Context 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 11-3 Create an API Context 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);
  ...
}
 
	...

11.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 11-4 Create a Handler
... // Get a reference to the XmlRpcClient String url = "http://host1:8080/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 11-4 Create a Handler

...
// Get a reference to the XmlRpcClient
String url = "http://host1:8080/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
  ...
}
...

^{1 (TableFootnote) In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.}

^{2 (TableFootnote) In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.}

^{3 (TableFootnote) This method changes the category list held in memory. To make the changes permanent, you must call updateCategories.}

^{4 (TableFootnote) In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.}

^{5 (TableFootnote) In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.}

^{6 (TableFootnote) In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.}

^{7 (TableFootnote) In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.}

^{8 (TableFootnote) In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.}

^{9 (TableFootnote) In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.}

^{10 (TableFootnote) In addition to the objects listed, all methods return a response_code and, if an error occurs, a response_message.}

11.1 General Process Flow

11.2 Using the Subscriber API

11.2.1 Managing Transactions

11.2.2 Example of Creating an IApiContext Object

11.2.3 Example of Creating a Service

11.3 XML-RPC Implementation

11.3.1 Accessing Content Delivery Server

11.3.2 Using XML-RPC Handlers for the Subscriber API

11.3.2.1 Guidelines for Calls to XML-RPC Methods

11.3.2.2 AuthenticationHandler

11.3.2.3 CategoryHandler

11.3.2.4 ContentHandler

11.3.2.5 DownloadHandler

11.3.2.6 GiftingHandler

11.3.2.7 MessageHandler

11.3.2.8 StreamingHandler

11.3.2.9 SystemHandler

11.3.2.10 UserHandler