11 订户 API

通过订户 API，可以访问由 Content Delivery Server 维护的数据。使用此 API 可以获取必要的数据来创建自己的客户机应用程序，以便订户访问由 Content Delivery Server 管理的内容。

位于具备 Content Delivery Server Subscriber Portal 组件的服务器上以 Java 编程语言编写的客户机可以直接调用订户 API。如果编写客户机的编程语言不是 Java，或者客户机所在的服务器不包含 Subscriber Portal，则客户机必须通过 XML-RPC（Remote Procedure Call，远程过程调用）实现来访问订户 API。

订户 API 包括客户机可能使用的以下类和接口：

ApiContextFactory - 此类创建包含订户特征（如语言环境、设备型号和移动 ID）的 IApiContext 对象。

ApiServiceFactory - 此类为特定订户创建服务。通过服务可以访问相关信息的集合。例如，通过内容服务可以访问订户上次购物的列表、各个项目的详细信息和订户书签内容。

ApiUtil - 此类提供多种功能，例如启动事务或检查数据库版本。

IApiContext - 此接口提供当前订户的相关信息。

ICategoryService - 此接口提供对类别树和订户类别列表的访问。

IContentService - 通过此接口可以访问内容以进行浏览、查找、检索和购买，还可以访问预览文件。

IDownloadService - 此接口提供对内容描述符的访问。

IGiftingService - 订户可通过此接口将礼品或有关某一项的消息发送给其他订户。

IMessageService - 通过此接口可以将消息发送给此订户或其他订户。消息可以是电子邮件、MMS、SMS 或 WAP 推送格式。

IStreamingService - Content Delivery Server 可通过此接口访问流式传输的内容，流式传输服务器可通过此接口验证内容请求。

ISystemService - 此接口提供对系统级内容（如语言环境、内容类型和设备型号）的访问。

IUserService - 此接口提供对订户相关信息的访问，并可用来创建新的订户帐户。

CDSException - 出现错误时订户 API 抛出的异常。

有关这些类以及其他类的其他信息，请参见 $CDS_HOME/javadoc/cdsapi/index.html 中的 Javadoc 工具的 HTML 输出。

11.1 一般处理流程

本节介绍可能需要客户机应用程序执行的常规任务。本节中使用的类名是指构成订户 API 的类。如果您使用 XML-RPC 访问 Content Delivery Server 数据，请参见 11.3 XML-RPC 实现以获得等效的处理程序信息。

可以使用验证密钥来验证对 Content Delivery Server 的访问请求。该密钥包含在 IApiContext 对象中，它是在创建 IApiContext 对象时生成的。需要使用验证密钥才能创建服务；如果在指定时间（几分钟）内未使用该密钥，它将会失效。默认时间为 10 分钟。要更改此时间，请在 $CDS_HOME/deployment/deployment-name/conf/SubscriberPortal.properties 文件中设置 subscriberApi.authkey.timeout.minutes 属性。如果密钥失效，则必须创建新的 IApiContext 对象以获得新密钥。

通常，您为订户接口创建的客户机应用程序包含多个操作，如下面列表中所述。

通过调用 ApiContextFactory 来创建 IApiContext。

IApiContext 对象说明特定订户或匿名订户。所有服务都使用此对象检索特定于对象所说明的订户的数据。通常，您应该为每个用户会话创建一个 IApiContext 对象，并将验证密钥存储在 HttpSession 对象中。要获得验证密钥，请调用 IApiContext.getAuthKey 方法。有关样例代码，请参见 11.2.2 IApiContext 对象创建示例。

通过调用 ApiServiceFactory 来创建获得要使用的信息所需的服务。

创建的服务取决于要执行的任务。例如，要使某位订户能够为另一订户购买礼品，请创建 IGiftingService 对象。要为订户提供已购买内容的列表，请创建 IContentService 对象。您必须具有验证密钥才能创建服务。创建的每个服务都提供特定于 IApiContext 对象所说明的订户的数据。有关样例代码，请参见 11.2.3 创建服务的示例。

通过为所创建的服务调用方法来检索要使用的信息。

例如，如果创建了 IContentService，则可以调用 getCampaigns 方法以获得订户可用的活动列表，或调用 getPurchases 方法以获得订户已购买的项列表。

注销 Content Delivery Server。

在完成后，可通过调用 IApiContextFactory.removeApiContext 方法删除验证密钥。

11.2 使用订户 API

订户 API 的类位于软件包 com.sun.content.server.subscriberapi 中。此软件包包含在以下某个位置的 subscriberportal.jar 文件中：

对于 Sun Java System Application Server，该文件位于 $CDS_HOME/deployment/deployment-name/sun/domains/server-domain/applications/j2ee-modules/CDSSubscriberPortal/WEB-INF/lib。

对于 WebLogic Server，该文件位于 $CDS_HOME/deployment/deployment-name/weblogic/domains/server-domain/applications/subscriber/WEB-INF/lib。

deployment-name 是在部署 Catalog Manager 时指定的名称；server-domain 是在部署配置文件中为 app.server.domain 属性指定的值。

如果您的客户机应用程序是 Java 应用程序，则请使用 subscriberportal.jar 文件中的订户 API 类创建您的客户机。编译应用程序时，此 JAR 文件必须位于类路径中。

要执行应用程序，请将包含客户机的 JAR 文件置于 $CDS_HOME/deployment/deployment-name/.../lib 目录中（该目录还包含 subscriberportal.jar 文件）。客户机必须运行在与随 Content Delivery Server 一起提供的 Subscriber Portal 相同的 Web 应用程序结构中。不支持独立的 Java 应用程序。

如果客户机不是 Java 应用程序或者与 Subscriber Portal 不在同一台服务器上，请参见 11.3 XML-RPC 实现获取有关通过 XML-RPC 访问订户 API 的信息。

11.2.1 管理事务

每次创建服务实例并调用其方法来执行任务时，都会有事务发生。应用程序必须按照如下步骤中说明的方式管理 Content Delivery Server 事务：

1. 调用服务之前，请调用 ApiUtil.initTransaction 方法指明事务的起点。

2. 如果事务成功完成，请调用 ApiUtil.commitTransaction 方法提交完成的工作。如果处理事务的过程中出错，请调用 ApiUtil.rollbackTransaction 方法终止工作并将数据恢复到以前的状态。

3. 事务资源必须在调用 ApiUtil.disposeTransaction 方法的 finally 块中释放。

有关样例实现，请参见 11.2.2 IApiContext 对象创建示例和 11.2.3 创建服务的示例中的代码示例。

11.2.2 `IApiContext` 对象创建示例

以下节选代码显示如何创建 IApiContext 对象。

编码样例 11-1 使用 Java 类文件来创建 `IApiContext` 对象
... 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-1 使用 Java 类文件来创建 IApiContext 对象

...
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 创建服务的示例

以下节选代码显示如何创建内容服务以及如何使用该服务购买内容。

编码样例 11-2 创建服务
... 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-2 创建服务

...
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 实现

如果客户机不是 Java 应用程序，或者没有运行在具有 Content Delivery Server 的服务器上，则客户机必须使用 XML-RPC 与 Content Delivery Server 进行通信。通过 XML-RPC，客户机可以在进行传输和数据编码时分别使用 HTTP 和 XML 进行远程过程调用。通过使用 Internet 上的绑定，可以将 XML-RPC 与许多不同编程语言一起使用。订户 API 的所有这些功能通过 XML-RPC 才可以使用。

注 - 有关 XML-RPC 的教程不在本文档的范围之内。您可以从 Internet 的多个不同 Web 站点中获取有关编写使用 XML-RPC 的应用程序方面的信息。

11.3.1 访问 Content Delivery Server

要从 Content Delivery Server 获取数据，客户机必须能够与 Content Delivery Server 进行通信。请要求网络管理员确保客户机可以访问 Content Delivery Server，并且任何所需的代理或防火墙均已配置为允许该访问。

此外，Content Delivery Server 还必须认可客户机已授权执行数据请求。$CDS_HOME/deployment/deployment-name/conf/SubscriberPortal.properties 文件中的 subscriberApi.xml-rpc.trustedHosts 属性包含请求将被接受的主机列表。

将 subscriberApi.xml-rpc.trustedHosts 属性设置为客户机所在主机的主机名和 IP 地址，而不管是否与 Content Delivery Server 位于同一主机。要接受任何主机的请求，请保留此值为空。要接受多个主机的请求，请使用逗号分隔主机名或 IP 地址，例如：

subscriberApi.xml-rpc.trustedHosts=127.0.0.1,localhost

11.3.2 使用订户 API 的 XML-RPC 处理程序

不论是直接访问订户 API 还是通过 XML-RPC 访问，应用程序的一般流程（请参见 11.1 一般处理流程）是类似的。在这两种情况下，需要具有 API 上下文对象才能访问服务。在直接访问订户 API 时，将使用验证密钥来创建服务。在使用 XML-RPC 时，可以使用 AuthenticationHandler 获取将传递到每种方法的 API 上下文对象。

XML-RPC 实现中的处理程序执行与订户 API 服务相同的功能。每个处理程序及其相应的服务都具备带有等效参数的等效方法。

本节介绍以下主题：

XML-RPC 方法调用的指导

AuthenticationHandler

CategoryHandler

ContentHandler

DownloadHandler

GiftingHandler

MessageHandler

StreamingHandler

SystemHandler

UserHandler

方法的参数

11.3.2.1 XML-RPC 方法调用的指导

请按以下指导原则编写处理程序调用代码。样例代码是使用 Java 编程语言编写的。

将调用的方法参数置于一个散列表中。将散列表置于向量中。

...
// Set up the input parameters
Vector parameters = new Vector();
Hashtable ht = new Hashtable();
ht.put("username", "user1");
ht.put("password", "cryptic1");
parameters.addElement(ht);
...

要调用方法，请传递方法的名称，以及为包含参数的散列表创建的向量。将返回一个散列表。方法调用必须包含处理程序的名称，例如：AuthenticationHandler.getApiContext。

...
// 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"));
}

如果方法已成功执行，则提取散列表中返回的值。如果方法未返回任何值，则散列表只包含响应代码。

...
  // 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");
  ...

以下几节介绍可以使用的处理程序。11.3.3 使用处理程序的示例中提供示例。

11.3.2.2 `AuthenticationHandler`

AuthenticationHandler 等效于 ApiContextFactory 类。该处理程序创建包含订户特征的 API 上下文对象。API 上下文对象等效于 IApiContext 对象。调用处理程序中的方法的指导在 11.3.2.1 XML-RPC 方法调用的指导中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接，例如：

AuthenticationHandler.getApiContext

下表介绍 AuthenticationHandler 的方法。

表 11-1 `AuthenticationHandler` 的方法
方法名称	描述	参数	返回^{^[1]}
`getAnonymousApiContext`	为匿名订户创建 API 上下文对象。	localeCode, modelId	apiContext
`getApiContext`	根据提供的信息验证订户，并创建包含该订户信息的 API 上下文对象。	下列项目之一： username 和 password mobileId uniqueId subscriberId requestHeaders	apiContext

11.3.2.3 `CategoryHandler`

CategoryHandler 等效于 ICategoryService 接口。该处理程序提供对类别树和订户类别列表的访问。调用处理程序中的方法的指导在 11.3.2.1 XML-RPC 方法调用的指导中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接，例如：

CategoryHandler.getCategory

下表介绍 CategoryHandler 的方法。

表 11-2 `CategoryHandler` 的方法
方法名称	描述	参数	返回 ^[2]
`getCategory`	获取当前订户的指定类别。	apiContext, categoryId, includeContentCount	category
`getCategoryBranch`	从 `categoryId` 中指定的类别开始，获取整个类别树分支。要获取整个树，请指定根类别。返回的类别包含 `contentTypeIdList` 中列出的内容类型以及 `statusList` 中列出的状态。如果未提供 `contentTypeIdList`，则考虑所有内容类型。如果未提供 `statusList`，则考虑所有状态。	apiContext、categoryId、contentTypeIdList（可选）、statusList（可选）、includeContentCount	category
`getNotEmptySubCategories`	对于 `categoryId` 中指定的类别，获取子类别列表，这些子类别包含 `contentTypeIdList` 中列出的内容类型，及 `statusList` 中列出的状态。如果未提供 `contentTypeIdList`，则考虑所有内容类型。如果未提供 `statusList`，则考虑所有状态。	apiContext、categoryId、contentTypeIdList（可选）、statusList（可选）、includeContentCount	categoryList
`getSubCategories`	对于 `categoryId` 中指定的类别，获取所有子类别的列表。	apiContext, categoryId, includeContentCount	categoryList
`getRootCategory`	获取当前订户的根类别。	apiContext, includeContentCount	category
`hideCategory`^{^[3]}	隐藏 `categoryIds` 中指定的、订户选择不查看的类别，并返回更新后的列表。	apiContext, categoryIds, categoryList	categoryList
`moveCategoryDown`^*	在下一活动类别下方将 `categoryIds` 中指定的每个类别向下移动一个位置，并返回更新后的列表。	apiContext, categoryIds, categoryList	categoryList
`moveCategoryUp`^*	在下一活动类别上方将 `categoryIds` 中指定的每个类别向上移动一个位置，并返回更新后的列表。	apiContext, categoryIds, categoryList	categoryList
`showCategory`*	显示 `categoryIds` 中指定的、订户已选择的类别，并返回更新后的列表。	apiContext, categoryIds, categoryList	categoryList
`updateCategories`	为 `categoryList` 中的类别更新数据库中的信息。	apiContext, categoryList	无

11.3.2.4 `ContentHandler`

ContentHandler 等效于 IContentService 接口。该处理程序提供对内容的访问，以便完成浏览、查找、检索和购买。调用处理程序中的方法的指导在 11.3.2.1 XML-RPC 方法调用的指导中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接，例如：

ContentHandler.browseContent

下表介绍 ContentHandler 的方法。

表 11-3 `ContentHandler` 的方法
方法名称	描述	参数	返回^{^[4]}
`addBookmark`	将一项内容添加到订户的书签内容列表。	apiContext, contentId	无
`browseContent`	获取 `categoryId` 指定类别中具有 `contentTypeIdList` 指定类型的 `numberToReturn` 指定数量的项目。如果未提供 `contentTypeIdList`，则包含所有内容类型。此方法已过时。请使用 searchContent 方法的新版本。	apiContext、categoryId、contentTypeIdList（可选）、startIndex、numberToReturn	contentList, totalSize
`cancelSubscription`	取消订户对某项内容的订阅。	apiContext, contentId	无
`clearBookmarks`	清除订户的书签内容列表。	apiContext	无
`deleteBookmark`	从订户的书签内容列表中删除某项内容。	apiContext, contentId	无
`getAnonymousCampaignForCoupon`	获取与指定礼券相关的活动信息。如果订户是匿名的，请调用此方法。	apiContext, couponCode	campaign
`getBookmarks`	获取订户书签中已有项目列表。	apiContext	contentList
`getBundledItems`	获取包中的内容项。	apiContext, contentId, criteria	contentList, totalSize
`getCampaign`	获取活动信息。	apiContext, campaignId	campaign
`getCampaignForCoupon`	获取与指定礼券相关的活动信息。如果已知订户，请调用此方法。	apiContext, couponCode	campaign
`getCampaignItems`	获取与活动相关的内容列表。	apiContext, campaignId, startIndex, numberToReturn	contentList, totalSize
`getCampaigns`	获取订户可用的活动列表。	apiContext	campaignList
`getContentByClassId`	获取由 `contentClassId` 标识的内容的特定版的内容 ID。	apiContext, contentClassId	contentId
`getContentByKeyword`	获取由 `contentKeyword` 标识的内容的特定版的内容 ID。	apiContext, contentKeyword	contentId
`getContentDetails`	获取某项内容的信息。	apiContext, contentId, criteria	content
`getContentDetailsCriteria`	获取一个空条件对象，它可用于接受条件作为参数的方法。	apiContext	criteria
`getContentDetailsList`	获取 `contentIdList` 中指定的每项内容的信息。	apiContext, contentId, criteria	contentList
`getContentSummary`	获取某项内容的概要信息。	apiContext, contentId	contentSummary
`getDeliveryType`	获取用于传送此内容的传送类型。	apiContext, contentId	deliveryType
`getPurchasedBundles`	获取订户购买的包含 `contentId` 中指定内容项的包列表。	apiContext, contentId	contentList, totalSize
`getPurchases`	获取订户已购买内容列表。	apiContext	purchaseList
`getSupportedModels`	获取可运行内容的型号列表。	apiContext, contentId	modelList
`getTicket`	获取由 `contentId` 标识的内容的购买证明书。	apiContext、contentId、bundleId（仅当内容是包的一部分才指定）	codedTicket
`hasPurchases`	确定订户是否购买任何内容。	apiContext	hasPurchases
`isBookmarked`	确定订户是否为内容编制书签。	apiContext, contentId	isBookmarked
`isContentInCampaign`	确定 `contentId` 指定的内容是否位于 `campaignId` 指定的活动中。	apiContext, contentId, campaignId	isContentInCampaign
`isMMSCapable`	确定内容是否可以使用 MMS 推送到设备。	apiContext, contentId	isMMSCapable
`isSMSCapable`	确定是否可以使用 SMS 将内容推送到设备。	apiContext, contentId	isSMSCapable
`purchaseContent`	购买内容。如果指定了 `campaignID`，则购买属于活动一部分的内容。匿名订户无法使用。	apiContext、contentId、campaignId（可选）、isSkipTrial	无
`requestContent`	将内容发送给某个订户。必须先购买内容。	apiContext, contentId, requestParams, maxNumberToSend	wasDelivered
`searchContent`	获取与查找查询匹配的内容的内容概要列表。	apiContext, searchQuery, sortKeyMap, categoryId, startIndex, numberToReturn	contentList, totalSize
`searchContent`	获取匹配查找条件的内容列表。从 `categoryId` 中指定的类别开始查找类别树。要查找所有内容，请指定根类别（请参见 `CategoryHandler` 中的 getRootCategory 方法）。此方法已过时。请使用新版本。	apiContext, categoryId, contentTypeIdList（可选）、keyword、startIndex、numberToReturn	contentList, totalSize

11.3.2.5 `DownloadHandler`

DownloadHandler 等效于 IDownloadService 接口。该处理程序提供对下载内容所需描述符的访问。调用处理程序中的方法的指导在 11.3.2.1 XML-RPC 方法调用的指导中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接，例如：

DownloadHandler.downloadConfirm

下表介绍 DownloadHandler 的方法。

表 11-4 `DownloadHandler` 的方法
方法名称	描述	参数	返回^{^[5]}
`downloadConfirm`	确认内容已下载到设备。	apiContext, codedTicket, isOneStepConfirm, status	无
`downloadContent`	为 `contentId` 指定的内容项下载二进制文件。	apiContext, contentId	contentLength, contentType, descriptorData
`downloadContentDescriptor`	创建内容描述符文件，并将其返回给调用者。	apiContext, codedTicket	contentLength, contentType, descriptorData
`downloadDelete`	确认从设备中删除了该内容。	apiContext, codedTicket, isOneStepConfirm, status	无
`downloadJAD`	创建 Java 应用程序描述符 (Java Application Descriptor , JAD) 文件，并将其返回给调用者。	apiContext, codedTicket	contentLength, contentType, descriptorData
`downloadJAM`	为 iAppli 应用程序创建应用程序描述符文件，并将其返回给调用者。	apiContext, codedTicket	contentLength, contentType, descriptorData
`pushMMSContent`	使用 MMS 将内容推送到设备。此方法已过时。请使用 `pushMMSContentByTicket` 方法。	apiContext, contentId	无
`pushMMSContentByTicket`	使用 MMS 将 `codedTicket` 所标识的内容推送到设备。	apiContext, codedTicket	无
`pushSMSContentBinary`	使用 SMS 将外部内容推送到设备。	apiContext, mobileId, contentBinary, mimeType, contentType, smsParams	无
`pushSMSContentByTicket`	使用 SMS 将 `codedTicket` 所标识的内容推送到设备。	apiContext, codedTicket, smsParams	无
`sendInstall`	将内容安装文件推送到订户设备。	apiContext, codedTicket	无

11.3.2.6 `GiftingHandler`

GiftingHandler 等效于 IGiftingService 接口。该处理程序将有关内容的礼品或通知发送到其他订户。调用处理程序中的方法的指导在 11.3.2.1 XML-RPC 方法调用的指导中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接，例如：

GiftingHandler.createGifting

下表介绍 GiftingHandler 的方法。

表 11-5 `GiftingHandler` 的方法
方法名称	描述	参数	返回^{^[6]}
`cancelGifting`	取消礼品订阅。	apiContext, giftId	无
`checkAndExpireGifting`	确定礼品是否已过期。	apiContext, gifting	isGiftExpired
`getGiftingById`	获取 `giftId` 指定的有关礼品的信息。	apiContext, giftId, filter, bundledContentId	gifting
`getGiftingByTicket`	获取 `giftTicket` 指定的有关礼品的信息。	apiContext, giftTicket, filter, bundledContentId	gifting
`getGiftingsByGifter`	获取订户给出的所有礼品的信息。	apiContext, filter	giftingList
`getGiftingsByRecipient`	获取订户接收到的所有礼品的信息。	apiContext, filter	giftingList
`giftContent`	购买某项内容作为给其他订户的礼品。	apiContext、contentId、campaignId（可选）、recipientApiContext、message、giftedDownloads、giftedSubscriptions	giftId
`isGiftingUsed`	确定收件人是否需要礼品所提供的所有用途。	apiContext, gifting	isGiftingUsed
`messageContent`	发送有关某项内容的消息给其他订户。	apiContext, contentId, recipientApiContext, message	giftId

11.3.2.7 `MessageHandler`

MessageHandler 等效于 IMessageService 接口。该处理程序将电子邮件、SMS、WAP 推送以及 MMS 消息发送到当前订户或其他订户。调用处理程序中的方法的指导在 11.3.2.1 XML-RPC 方法调用的指导中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接，例如：

MessageHandler.sendMessageToSelf

下表介绍 MessageHandler 的方法。

表 11-6 `MessageHandler` 的方法
方法名称	描述	参数	返回^{^[7]}
`sendMessageToMobileId`	将消息发送到提供的移动 ID 所指定的号码。	apiContext, subject, message, url, mobileId, contentId, messageCategory	无
`sendMessageToSelf`	将消息发送到当前订户。	apiContext, messageType, subject, message, url, contentId, messageCategory	无
`sendMessageToSubscriberId`	将消息发送到提供的订户 ID 所标识的订户。	apiContext, messageType, subject, message, url, subscriberId, contentId, messageCategory	无
`sendMessageToUsername`	将消息发送到提供的用户名所标识的订户。	apiContext, messageType, subject, message, url, username, contentId, messageCategory	无
`sendMMSContent`	使用 MMS 推送将消息发送到当前订户。	apiContext, mobileId, contentBinary, name, contentType, mimeType, subject, message, modelId, contentId, messageCategory	无

11.3.2.8 `StreamingHandler`

StreamingHandler 等效于 IStreamingService 接口。该处理程序为 Content Delivery Server 提供了有关流式传输会话的信息，流式传输服务器可通过该处理程序验证内容请求。调用处理程序中的方法的指导在 11.3.2.1 XML-RPC 方法调用的指导中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接，例如：

StreamingHandler.authenticate

下表介绍 StreamingHandler 的方法。

表 11-7 `StreamingHandler` 的方法
方法名称	描述	参数	返回^{^[8]}
`authenticate`	验证 Content Delivery Server 是否已知请求流式传输内容的订户。	apiContext	isAuthenticated
`authorize`	验证请求流式传输内容的订户是否购买了所请求的项。	apiContext, codedTicket	isAuthenticated
`endSession`	通知 Content Delivery Server 流式传输会话已结束。	apiContext, codedTicket	无
`errorInSession`	通知 Content Delivery Server 在流式传输会话期间出现错误。	apiContext, codedTicket	无
`startSession`	通知 Content Delivery Server 流式传输会话已开始。	apiContext, codedTicket	无

11.3.2.9 `SystemHandler`

SystemHandler 等效于 ISystemService 接口。该处理程序提供对系统级数据的访问，例如内容类型，语言环境和型号。调用处理程序中的方法的指导在 11.3.2.1 XML-RPC 方法调用的指导中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接，例如：

SystemHandler.getContentTypes

下表介绍 SystemHandler 的方法。

表 11-8 `SystemHandler` 的方法
方法名称	描述	参数	返回^{^[9]}
`createTicket`	为订户创建证明书，用来检索某项内容。	apiContext, contentId	ticket
`getContentTypes`	获取 Content Delivery Server 中定义的所有内容类型的列表。	apiContext	contentTypeList
`getCountries`	获取 Content Delivery Server 中包含的所有国家/地区的列表。	apiContext	countryList
`getCountry`	获取单个国家/地区的信息。	apiContext, countryCode	country
`getDefaultLocale`	获取系统的默认语言环境。	apiContext	locale
`getDefaultMode`l	获取默认设备模型。	apiContext	modelId
`getLocale`	获取单个语言环境的信息。	apiContext, localeCode	locale
`getLocales`	获取 Content Delivery Server 中包含的所有语言环境的列表。	apiContext	localeList
`getManufacturers`	获取 Content Delivery Server 中包含的所有设备生产商的名称。	apiContext	manufacturerList
`getModel`	获取设备的信息。	apiContext, modelId	model
`getModelId`	获取与 `modelId` 指定的用户代理相关的设备内部 ID。	apiContext, userAgent	modelId
`getModels`	获取 Content Delivery Server 支持的所有设备的列表。	apiContext	modelList
`getModelsForManufacturer`	获取 Content Delivery Server 中给定生产商的型号。仅返回未被隔离的型号。	apiContext, manufacturer	modelList
`isPushEnabled`	确定订户的设备是否是可推送的。	apiContext, modelId	isPushEnabled
`isTicketValid`	确定订户是否可以使用某项内容的证明书。	apiContext, ticket, contentId	isTicketValid
`sendEvent`	发送 `eventType` 中指定的系统事件。此方法已过时。不再需要使用此功能。	apiContext、subscriberId、mobileId、contentId（可选）、eventType	无
`sendEventWithParameters`	使用一组事件参数来发送系统事件。	apiContext, requestParams	无

11.3.2.10 `UserHandler`

UserHandler 等效于 IUserService 接口。通过此处理程序可以访问订户的有关信息以及创建新的订户帐户。调用处理程序中的方法的指导在 11.3.2.1 XML-RPC 方法调用的指导中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接，例如：

UserHandler.getSubscriberId

下表介绍 UserHandler 的方法。

表 11-9 `UserHandler` 的方法
方法名称	描述	参数	返回^{^[10]}
`disableSubscriberBySubscriberId`	禁用订户 ID 所标识订户的帐户。	apiContext, subscriberId	无
`disableSubscriberByUsername`	禁用用户名所标识订户的帐户。	apiContext, username	无
`getSubscriberId`	获取用户名所标识订户的订户 ID。	apiContext, username	subscriberId
`getUserPreferences`	获取订户设置的首选项。	apiContext	preferenceList
`getUserProperties`	获取当前订户的信息。	apiContext	propertyList
`getUserPropertiesBySubscriberId`	获取订户 ID 所标识订户的信息。	apiContext, subscriberId	propertyList
`getUserPropertiesByUsername`	获取用户名所标识订户的信息。	apiContext, username	propertyList
`provision`	用外部订户数据库的信息填充 Content Delivery Server 中的订户帐户。	apiContext, uniqueId, modelId, mobileId, localeCode	subscriberId
`resetPasswordBySubscriberId`	将订户 ID 所标识订户的密码设置为系统生成的值。	apiContext, subscriberId, passwordRequiresReset	password
`resetPasswordByUsername`	将用户名所标识订户的密码设置为系统生成的值。	apiContext, username, passwordRequiresReset	password
`setLocaleCode`	更改订户的语言环境代码。	apiContext, localeCode	无
`setModelId`	将型号 ID 更改为匹配订户使用的新设备。	apiContext, modelId	无
`setPassword`	更改订户的密码。	apiContext, password	无
`setUserPreferences`	设置订户选择的首选项。这些首选项管理显示给用户的信息。	apiContext, preferenceList	无
`setUserProperties`	设置订户信息。	apiContext, propertyList	无
`signup`	在 Content Delivery Server 和任何外部订户数据库中创建订户帐户。	apiContext, username, password, modelId, mobileId, uniqueId, localeCode	subscriberId
`signupWithPropertiesAndPreferences`	在 Content Delivery Server 和任何外部订户数据库中创建订户帐户，并为该订户设置信息和首选项。	apiContext, username, password, modelId, mobileId, uniqueId, localeCode, propertyList, preferenceList	subscriberId

11.3.2.11 方法的参数

下表介绍方法的参数。容器对象（例如包含元素的散列表和向量）也在该表中进行介绍。

表 11-10 方法参数
参数	类型	描述
`addressLine1`	`字符串`	订户地址的第一行。
`addressLine2`	`字符串`	订户地址的第二行。
`apiContext`	`散列表`	订户有关信息的容器。该容器包含以下各项： subscriberId username localeCode mobileId modelId uniqueId isAnonymous isProvisioned isRegistered passwordRequiresReset isCategoryCustomized roleId propertyMap 对于匿名订户，仅包含 `subscriberId`、`localeCode` 和 `modelId`。
`bundledContentId`	`整型`	包中由 Content Delivery Server 指定给单个项的内部 ID。
`bundleId`	`整型`	Content Delivery Server 为当前使用的包指定的内部 ID。
`campaign`	`散列表`	活动有关信息的容器。该容器包含以下各项： campaignId name description campaignSubject campaignMessage campaignDiscount campaignExpiration
`campaignDiscount`	`双精度型`	活动中项目的折扣百分比。
`campaignExpiration`	`日期`	活动到期日期。如果活动到期，则返回 `Null`。
`campaignId`	`整型`	Content Delivery Server 为当前使用的活动指定的内部 ID。
`campaignList`	`向量`，campaign 类型的元素	订户可以使用的活动列表。
`campaignMessage`	`字符串`	包含在发送给订户的发布活动通知中的促销消息。
`campaignSubject`	`字符串`	添加到发送给订户的发布活动电子邮件通知的主题。
`category`	`散列表`	类别有关信息的容器。该容器包含以下各项： categoryId name description parentCategoryId isLeafNode isActive displayOrder contentCount sortingQuery subCategoryList（仅在由 `CategoryHandler` 的 getCategoryBranch 方法返回时才包含）
`categoryId`	`整型`	Content Delivery Server 为当前使用的类别指定的内部 ID。
`categoryIds`	`向量`，`整型`类型的元素	类别 ID 的列表。类别是由 Content Delivery Server 指定的内部 ID 标识的。
`categoryList`	`向量`，category 类型的元素	类别列表。
`city`	`字符串`	订户地址的城市。
`codedTicket`	`字符串`	标识用于下载请求的购买证明书的字符串。
`contactPhone`	`字符串`	订户的电话号码。
`content`	`散列表`	某项内容有关信息的容器。该容器包含以下各项： 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`	`字符串`	内容的二进制格式。
`contentClassId`	`整型`	在 Catalog Manager 中标识内容项的唯一标识符。类 ID 是指一个项及其所有关联的版本。
`contentCount`	`整型`	类别中内容的项目数。
`contentId`	`整型`	Content Delivery Server 为当前使用的内容项指定的内部 ID。
`contentIdList`	`向量`，contentId 类型的元素	内容 ID 的列表。
`contentKeyword`	`字符串`	用于标识内容的关键字，通常用于使用 SMS 直接传送到设备的内容。
`contentLength`	`整型`	内容的大小。
`contentList`	`向量`	内容项的列表。在由 `ContentHandler` 的 getContentDetailsList 方法返回时，向量元素的类型为 content。在由 `ContentHandler` 的其他方法返回时，向量元素的类型为 contentSummary。
`contentSummary`	`散列表`	内容项有关概要信息的容器。该容器包含以下各项： contentId name contentType shortDescription submitDate contentClassId longDescription sizeInKB developerName contentKeyword isBundle
`contentType`	`字符串`	所使用的内容类型。该类型必须是 contentTypeList 中定义的某一项内容类型。在由 DownloadHandler 的方法返回时，这是二进制数据或描述符的 MIME 类型。
`contentTypeIdList`	`向量`，`整型`类型的元素	内容类型 ID 的列表。内容类型是由 Content Delivery Server 指定的内部 ID 标识的。
`contentTypeList`	`向量`，`散列表`类型的元素	有关 Content Delivery Server 中定义的每种内容类型的信息。每个元素均包含以下各项： id name
`country`	`散列表`	国家/地区有关信息的容器。该容器包含以下各项： countryCode name
`countryCode`	`字符串`	表示订户国家/地区的两字符 ISO 代码，例如，`US`。
`countryList`	`向量`，country 类型的元素	国家/地区的列表。
`couponCode`	`字符串`	标识订户用来购买内容的礼券的字符串。
`criteria`	`散列表`	内容项有关信息的容器。该容器包含以下各项： filter campaignId（可选） bundleId（仅当内容是包的一部分时） isSkipTrial licenseType
`customField`	`散列表`	包含为 Content Delivery Server 安装定义的定制字段相关信息的容器。该容器包含以下各项： customFieldId customFieldCustomKey customFieldNumber customFieldText customFieldTimestamp customFieldBoolean customFieldLabel customFieldDatatype customFieldScope
`customFieldBoolean`	`布尔型`	为`布尔型`类型的定制字段存储的值。
`customFieldCollection`	`向量`，customField 类型的元素	为安装定义的定制字段列表。
`customFieldCustomKey`	`字符串`	用于向 Content Delivery Server 标识定制字段的字符串。
`customFieldDatatype`	`字符串`	定制字段中存储的数据的类型。有效值为 `boolean`、`number`、`text` 和 `timestamp`。
`customFieldId`	`整型`	Content Delivery Server 为标识定制字段而指定的内部 ID。
`customFieldLabel`	`字符串`	用于在用户接口中标识定制字段的字符串。
`customFieldNumber`	`双精度型`	为 `number` 类型的定制字段存储的值。
`customFieldScope`	`字符串`	指定字段是适用于内容项，还是适用于内容项的版本。
`customFieldText`	`字符串`	为 `text` 类型的定制字段存储的值。
`customFieldTimestamp`	`日期`	为 `timestamp` 类型的定制字段存储的值。
`deliveryType`	`字符串`	用于传送内容的传送类型。有效值为： `ems` - 增强消息传送系统 `nsm` - Nokia 智能消息传送 `one_step_wap` - 一步 WAP `two_step_wap` - 两步 WAP
`description`	`字符串`	对象的描述。根据所调用的方法，该参数可以是类别、活动、设备或语言环境的描述。
`descriptorData`	字节`数组`	内容描述符的二进制形式，表示为采用 Base64 编码的数据。在由 `DownloadHandler` 的 `downloadContent` 方法返回时，这是内容二进制文件。
`developerName`	`字符串`	提交内容的开发者姓名。
`developerUrl`	`字符串`	提交内容的开发者 URL。
`devicePhone`	`字符串`	订户设备的电话号码。
`displayOrder`	`整型`	类别在类别列表中的位置。1 表示列表顶端。
`downloadCount`	`整型`	每一次购买所允许的下载次数。
`downloadPeriod`	`整型`	每一次购买所允许使用的天数。
`downloadPrice`	`双精度型`	下载内容收取的费用。
`downloadTimes`	`向量`，`字符串`类型的元素	下载内容所需的估计时间。每个元素对应于 networks 对象中的元素，表示通过相应类型网络进行下载所估计的时间。
`downloadUrl`	`字符串`	下载内容的 URL。
`emailAddress`	`字符串`	订户的电子邮件地址。
`eventType`	`字符串`	所使用的事件类型。使用 `sms_request_for_content` 来表示事件是有关内容项信息的请求。
`filter`	`散列表`	表示返回信息类型的布尔标志的容器。仅当标志包含在散列表中并设置为 `true` 时，与每个标志相关联的类型信息才会被返回。使用 `ContentHandler` 时，以下标志有效： `filterDetailsResourceBinaries` - 预览文件的二进制文件 `filterDetailsDownload` - 下载信息 `filterDetailsDownloadCount` - 下载计数 `filterDetailsIsBookmarked` - 信息书签 `filterDetailsResourceURLs` - 预览文件的 URL `filterDetailsPricingAndPurchase` - 价格和购买信息 `filterDetailsPricingAndGifting` - 礼品的价格信息 `filterDetailsIsValidOnCurrentModel` - 有关内容是否在设备上执行方面的信息 `filterDetailsIncludeRetailPrice` - 零售价格如果在过滤器中未指定 `filterDetailsResourceBinaries`，则预览对象中没有预览文件的二进制文件。如果尝试从预览对象中获取二进制文件，则会返回 Null。如果在过滤器中未指定 `filterDetailsResourceURLs`，则预览对象中没有预览文件的 URL。如果尝试从预览对象中获取 URL，则会返回空字符串。如果过滤器中不包含这两个标志，则 previewListMap 为 Null 并且无法访问预览文件。使用 `GiftHandler` 时，以下标志有效： `filterGiftsContent` - 有关内容的信息 `filterGiftsDownload` - 下载信息
`firstName`	`字符串`	订户的名字。
`gender`	`字符串`	订户的性别。有效值以及每个值所表示的含义如以下列表中所述： `M` - 订户是男性。 `F` - 订户是女性。
`giftCost`	`双精度型`	礼品的价格。
`giftedDownloads`	`整型`	礼品支付的下载数。
`giftedSubscriptions`	`整型`	礼品支付的订阅数。
`gifterId`	`整型`	购买礼品的订户的订户 ID。
`gifterMobileId`	`字符串`	购买礼品的订户的移动 ID。
`giftExpirationDate`	`日期`	礼品到期日期。
`giftId`	`整型`	Content Delivery Server 为当前使用的礼品指定的内部 ID。
`gifting`	`散列表`	礼品有关信息的容器。该容器包含以下各项： giftId giftStatus giftIsOnDevice contentId giftTicket gifterId gifterMobileId giftRecipientId giftRecipientMobileId giftRecipientModelId message giftedDownloads giftedSubscriptions giftCost giftPurchaseDate giftExpirationDate pricingDetails
`giftIsOnDevice`	`布尔型`	表示目标设备上是否存在礼品提供内容的标志。`True` 表示内容在设备上。`False` 表示内容不在设备上。
`giftingList`	`向量`，gifting 类型的元素	礼品的列表。
`giftPurchaseDate`	`日期`	购买礼品的日期。
`giftRecipientId`	`整型`	礼品接收订户的订户 ID。
`giftRecipientMobileId`	`字符串`	礼品接收订户的移动 ID。
`giftRecipientModelId`	`整型`	礼品接收订户的设备型号 ID。
`giftStatus`	`整型`	礼品状态。有效值以及每个值所表示的含义如以下列表中所述： `8` - 礼品已购买 `9` - 接收者已开始下载礼品 `10` - 礼品已成功下载 `11` - 礼品已过期 `12` - 礼品已取消 `13` - 礼品已退款
`giftTicket`	`字符串`	内部对象，用于验证订户是否可以访问礼品。
`hasPurchases`	`布尔型`	表示订户是否已购买内容的标志。`True` 表示订户已购买了内容。`False` 表示订户未购买内容。
`id`	`整型`	Content Delivery Server 为当前使用的语言环境、内容类型指定的内部 ID。
`includeContentCount`	布尔型	表示是否计算类别中的项数的标志。`True` 表示计算该数目。`False` 表示不计算该数目。
`isActive`	`布尔型`	包含在 category 对象中时，此标志表示是否将类别显示给订户。`True` 表示显示类别。`False` 表示不显示类别。包含在 content 对象中时，此标志表示内容是否处于活动状态。`True` 表示内容处于活动状态。`False` 表示内容处于不活动状态。
`isAnonymous`	`布尔型`	表示订户是否为匿名的标志。`True` 表示订户为匿名。`False` 表示订户为已知。
`isAuthenticated`	`布尔型`	此标志表示尝试访问流式传输内容的人员是否为可信的 Content Delivery Server 订户，或者该人是否购买了所请求的项。
i`sBookmarked`	`布尔型`	表示订户是否已为内容编制书签的标志。`True` 表示已为内容编制书签。`False` 表示没有为内容编制书签。
`isBundle`	`布尔型`	表示该项是否为包的标志。`True` 表示该项为包。`False` 表示该项不是包。
`isBundledItem`	`布尔型`	表示该项是否包含在包中的标志。`True` 表示该项是包的一部分。`False` 表示该项不是包的一部分。
`isCategoryCustomized`	布尔型	表示订户是否已定制显示的类别的标志。`True` 表示已定制类别。`False` 表示未定制类别。
`isContentInCampaign`	`布尔型`	表示是否活动中包含内容项的标志。`True` 表示活动中包含该项。`False` 表示活动中不包含该项。
`isDefault`	`布尔型`	表示是否该设备为默认设备的标志。`True` 表示该设备是默认设备。`False` 表示该设备不是默认设备。
`isDownloaded`	`布尔型`	表示是否已下载内容的标志。`True` 表示已下载内容项。`False` 表示尚未下载内容项。
`isDownloadRecurring`	`布尔型`	表示订户是否在超出已购买下载数量之后，自动支付其他下载的标志。`True` 表示自动续订。`False` 表示订户必须手动购买其他下载。
`isFree`	`布尔型`	表示内容是否为免费的标志。`True` 表示内容是免费的。`False` 表示必须购买内容。
`isGiftExpired`	`布尔型`	表示礼品是否已过期的标志。`True` 表示礼品已过期，无法再领取。`False` 表示礼品未过期。
`isGiftingUsed`	`布尔型`	表示是否接收订户已使用为礼品购买的所有用途的标志。`True` 表示购买的所有用途已使用。`False` 表示不是所有购买的用途都已使用。
`isLeafNode`	`布尔型`	表示类别是否具有子类别的标志。`True` 表示类别没有子类别。`False` 表示类别具有子类别。
`isMMSCapable`	`布尔型`	表示是否可以使用 MMS 将内容发送到设备的标志。`True` 表示可以使用 MMS。`False` 表示不可以使用 MMS。
`isOnDevice`	`布尔型`	表示内容项是否在订户设备上的标志。`True` 表示内容项在设备上。`False` 表示内容项不在设备上。
`isOneStepConfirm`	`布尔型`	表示使用一步还是两步下载的标志。`True` 表示一步下载。`False` 表示两步下载。
`isProvisioned`	`布尔型`	表示 Content Delivery Server 数据库中是否存在该订户的条目的标志。`True` 表示条目确实存在。`False` 表示订户是匿名的。
`isPurchaseRequiredBeforeDownload`	`布尔型`	表示是否必须购买内容才能下载的标志。`True` 表示必须首先购买内容。`False` 表示可以下载内容。
`isPushEnabled`	`布尔型`	表示设备是否为可推送的标志。`True` 表示设备是可推送的。`False` 表示设备不是可推送的。
`isRegistered`	`布尔型`	表示订户是否已在外部订户数据库中注册的标志。`True` 表示订户已注册。`False` 表示订户未注册。
`isSkipTrial`	`布尔型`	表示订户是否选择跳过试用的标志。`True` 表示订户选择跳过试用，以便可以立即购买内容。`False` 表示订户选择不跳过试用。
`isSMSCapable`	`布尔型`	表示是否可以使用 SMS 将内容发送到设备的标志。`True` 表示可以使用 SMS。`False` 表示不能使用 SMS。
`isSubscriptionExpired`	`布尔型`	表示是否订阅已过期的标志。`True` 表示订阅已过期。`False` 表示订阅未过期。
`isSubscriptionRecurring`	`布尔型`	表示是否自动续订的标志。`True` 表示自动续订。`False` 表示订户必须手动续订。
`isTicketValid`	`布尔型`	表示订户是否可以使用证明书来获取内容项的标志。`True` 表示订户可以使用证明书。`False` 表示订户不可以使用证明书。
`isTrialAvailable`	`布尔型`	表示内容是否能以试用方式进行使用的标志。`True` 表示允许试用。`False` 表示禁止试用。
`isUpdateAvailable`	`布尔型`	表示内容是否有可用更新的标志。`True` 表示有可用更新。`False` 表示无可用更新。
`isUnsubscribeAvailable`	`布尔型`	表示是否可以取消订阅内容的标志。`True` 表示可以取消订阅。`False` 表示没有订阅，或者订阅无法取消。
`isUsageConsumed`	`布尔型`	表示订户是否已使用了所有购买的内容用途的标志。`True` 表示所有购买的用途都已使用。`False` 表示不是所有购买的用途都已使用。
`isValidOnCurrentModel`	`布尔型`	表示是否可以在订户使用的型号上运行内容的标志。`True` 表示内容可以在该型号上运行。`False` 表示内容不可以在该型号上运行。
`keyword`	`字符串`	查找内容时要匹配的字符串。
`languageCode`	`字符串`	表示订户语言的两字符 ISO 代码，例如，`en`。
`largeIconUrl`	`字符串`	指向内容大图标的 URL。
`lastName`	`字符串`	订户的姓氏。
`licenseType`	`整型`	与内容关联的许可证类型。有效值以及每个值所表示的含义如以下列表中所述： `0` - 已购买内容。 `1` - 已将内容作为礼品发送。 `2` - 已将内容作为礼品接收。
`listEnd`	`字符串`	它与 `listStart` 共同指定了要返回的项的范围。按照字母顺序显示的列表以匹配指定字符串的项结尾。字符串区分大小写。指定为 Null 可在完整列表的结尾处结束。
`listStart`	`字符串`	它与 `listEnd` 共同指定了要返回的项的范围。按照字母顺序显示的列表以匹配指定字符串的项开头。字符串区分大小写。指定为 Null 可在完整列表的开头处开始。
`locale`	`散列表`	语言环境信息的容器。该容器包含以下各项： id countryCode languageCode localeCode description
`localeCode`	`字符串`	表示订户语言环境的字符串，例如，`en_US`。
`localeList`	`向量`，locale 类型的元素	语言环境的列表。
`longDescription`	`字符串`	来自信息有关内容的详细描述。
`manufacturer`	`字符串`	设备生产商的名称。
`manufacturerList`	`向量`，manufacturer 类型的元素	生产商的列表，按字母顺序排序。
`maxNumberToSend`	`整型`	在调用中传送的最大项数。如果存在的项数多于指定的数量，则不会发送内容。要传送所有项，请使用 `-1`。
`message`	`字符串`	要发送给订户的消息。
`messageCategory`	`整型`	要发送的消息类别。类别 1 到 7 发送到订户，类别 9 发送到 Catalog Manager 管理员。有效值以及每个值所表示的含义如以下列表中所述： `1` - 消息包含指向有关内容项详细信息的 URL。 `2` - 消息是源于移动的消息，包含指向有关内容项详细信息的 URL。 `3` - 消息包含内容二进制代码。 `4` - 消息包含礼品，并且包含指向有关内容项详细信息的 URL。 `5` - 消息包含通知，并且包含指向有关内容项详细信息的 URL。 `6` - 消息包含密码提醒。 `7` - 消息包含有关活动的信息。 `9` - 将新设备添加到 Content Delivery Server 中。
`messageType`	`整型`	要发送消息的类型。有效值以及每个值所表示的含义如以下列表中所述： `1` - 将消息发送到订户设备。 `2` - 将消息发送到订户电子邮件。
`middleName`	`字符串`	订户的中间名。
`mimeType`	`字符串`	内容的 MIME 类型。
`mobileId`	`字符串`	订户的电话号码。
`model`	`散列表`	设备信息的容器。该容器包含以下各项： modelId name description modelNumber manufacturer userAgentPattern isDefault
`modelId`	`整型`	Content Delivery Server 为当前使用的设备指定的内部 ID。
`modelList`	`向量`，model 类型的元素	设备的列表。
`modelNumber`	`字符串`	与设备相关的型号。
`name`	`字符串`	对象的名称。根据方法，该参数可以是类别、国家/地区、活动、设备或内容的名称。
`networks`	`向量`，字符串类型的元素	Content Delivery Server 已知的网络类型的列表。每个元素都对应 downloadTimes 向量中的元素，表示通过相应网络进行下载所估计的时间。
`notifyPromotions`	`布尔型`	表示订户是否希望接到促销通知。`True` 表示订户希望被通知。`False` 表示订户不希望被通知。
`numberOfDownloads`	`整型`	内容被所有订户下载的总次数。
`numberToReturn`	`整型`	列表中返回的项目数。要返回所有项，请指定 `-1`。
`parentCategoryId`	`整型`	Content Delivery Server 为当前使用类别的父类别指定的内部 ID。
`password`	`字符串`	订户不加密的密码。由 Content Delivery Server 执行加密。
`passwordRequiresReset`	`布尔型`	表示是否当订户登录时必须重置订户密码的标志。`True` 表示必须重置密码。`False` 表示无需重置密码。
`postalCode`	`字符串`	订户地址的邮政编码。
`preferenceList`	`散列表`	订户首选项的容器。此容器包含类型为 notifyPromotions 的项。要删除某个首选项，将相应的值设置为空字符串 (`')。
`preview`	`散列表`	预览相关信息的容器。该容器包含以下各项： previewBinary previewCaption previewLastModifiedDate previewMimeExtension previewMimeType previewPositionIndex previewTarget previewUrl
`previewBinary`	字节`数组`	预览文件的二进制形式，表示为采用 Base64 编码的数据。
`previewCaption`	`字符串`	用于标识预览的字符串。此字符串是可选的，并且可以为空。如果需要，代码可能会将空字符串替换为所选的字符串。
`previewLastModifiedDate`	`日期`	上次更改预览文件的日期。如果正在缓存预览文件，可以使用该日期来确定是否需要更新缓存。
`previewListMap`	`散列表`	WAP 预览和 Web 预览的预览文件的容器。该容器包含以下各项： wapPreviews webPreviews 如果在 filter 中未指定 `filterDetailsResourceBinaries` 和 `filterDetailsResourceURLs`，则该项为 Null。如果指定了其中一个标志，并且其中的一个目标没有预览文件，则该目标的列表为空。
`previewMimeExtension`	`字符串`	原始预览文件的扩展名，例如，`.jpg`。
`previewMimeType`	`字符串`	预览文件的 MIME 类型，例如，`image/jpg`。
`previewPositionIndex`	`整型`	预览集中文件的位置。预览集中的第一个文件的位置索引为 `1`。
`previewTarget`	`整型`	预览文件针对的浏览器类型。有效值以及每个值所表示的含义如以下列表中所述： `0` - 目标为 WAP 浏览器。 `1` - 目标为 Web 浏览器。
`previewUrl`	`字符串`	指向预览文件的 URL。
`pricingDetails`	`散列表`	内容项价格信息的容器。该容器包含以下各项： campaignDiscount downloadPrice downloadCount downloadPeriod isDownloadRecurring subscriptionPrice subscriptionFrequency isSubscriptionRecurring trialCount usagePrice usageCount isFree isTrialAvailable
`propertyList`	`向量`，`散列表`类型的元素	有关每个订户的信息。每个元素均包含以下各项： salutation firstName middleName lastName gender emailAddress addressLine1 addressLine2 city stateProvince postalCode countryCode contactPhone devicePhone
`propertyMap`	`散列表`	配置系统行为的名称-值对的集合。这些值是 Content Delivery Server 使用的内部值。
`purchaseDate`	`日期`	订户购买项目的日期。
`purchaseList`	`向量`，`散列表`类型的元素	有关订户购买的每项内容的信息。每个元素均包含以下各项： contentId name purchaseDate subscriptionExpiration pricingDetails isValidOnCurrentModel isSubscriptionExpired isUsageConsumed isUpdateAvailable isDownloaded isOnDevice codedTicket
`recipientApiContext`	`散列表`	礼品接收订户有关信息的容器。该容器包含以下各项： subscriberId username localeCode mobileId uniqueId modelId
`requestHeaders`	`散列表`	与 HTTP 请求相关联的 HTTP 头的容器。
r`equestParams`	`散列表`	提供事件相关信息的键-值对的容器。必须包含以下键： `request_data` - 请求中包含的数据，如内容或活动的未解析的 SMS 请求 `request_source` - 请求源，如将其发送到的短代码 `request_type` - 标识请求类型的字符串，如 `portal`、`mo_push` 或系统识别的其他值也可以包含系统识别的其他键。
`response_code`	`字符串`	表示是否成功执行方法的代码。`1` 表示成功完成。`-1` 表示发生错误。
`response_message`	`字符串`	方法返回的消息。
`roleId`	`整型`	指定给订户的角色。有效值以及每个值所表示的含义如以下列表中所述： `0` - 订户仅可以访问状态为 `Testing` 的内容。 `1` - 订户具有标准权限。
`salutation`	`字符串`	尊称，例如先生。
`score`	`双精度型`	该值表示找到的项目与查找查询的相关性有多大。值越大，表示相关性越大。有效值为 `0.0` 到 `1.0`。默认值为 `0.5`。
`searchFilter`	`散列表`	用于过滤内容查找结果的条件的容器。该容器包含以下各项： categoryId developerName keyword 容器必须包含至少一种类型的条件。
`searchQuery`	`字符串`	Apache Lucene 项目使用的查找查询表达式语言所定义的任何有效查找查询。有关其他信息，请参见 `http://lucene.apache.org/java/docs/queryparsersyntax.html`。
`shortDescription`	`字符串`	来自信息有关内容的简短描述。
`sizeInKB`	`字符串`	内容的大小。
`smallIconUrl`	`字符串`	指向内容小图标的 URL。
`smsParams`	`散列表`	将内容二进制代码推送到设备所需的参数的容器。散列表中的条目是字符串对，用于标识所需的每个参数的名称和值。
s`ortingQuery`	字符串	对查询结果进行排序时所依据的属性。这是 Vending Manager 管理员为某个类别设置的值。如果没有为该类别设置任何值，则使用最近的父类别的查询排序值。如果父类别未指定查询排序值，则使用 `null`。
`sortKeyMap`	`散列表`	对查找结果进行排序时依据的字段的容器。散列映射中的条目为`字符串`和`布尔型`对，其中字符串为排序字段的名称，布尔型表示是按升序还是按降序排序。值 `true` 表示升序；`false` 表示降序。
`startIndex`	`整型`	在项目列表中开始进行处理的位置。
`stateProvince`	`字符串`	订户地址的省/自治区/直辖市。
`status`	`字符串`	确认设备返回的状态字符串。有关 MIDP 应用程序可能返回的值，请参见 `http://www.jcp.org/jsr/detail/118.jsp`。
`statusList`	`向量`，`整型`类型的元素	内容状态的列表。有效值以及每个值所表示的含义如以下列表中所述： `1` - 内容处于活动状态。已储存内容，并且订户可以使用。 `2` - 内容处于不活动状态。已储存内容，但是订户无法使用。 `3` - 内容不可用。无法再从 Catalog Manager 获取内容。 `4` - 正在测试内容，只有指定了测试角色的订户才可以使用。
`subCategoryList`	`向量`，category 类型的元素	指定节点下面的类别列表。
`subject`	`字符串`	要发送给订户的消息主题。
`submitDate`	`日期`	提交内容的日期。
`subscriberId`	`整型`	Content Delivery Server 为订户帐户指定的内部 ID。
`subscriptionExpiration`	`日期`	订户订阅的到期日期。
`subscriptionFrequency`	`字符串`	订阅持续的时间段。有效值是 `daily`、`weekly`、`monthly` 和 `yearly`。
`subscriptionPrice`	`双精度型`	订阅内容需支付的价格。
`ticket`	`字符串`	内部对象，用于验证订户是否可访问所请求的内容。
`totalSize`	`整型`	找到的项目数。
`trialCount`	`整型`	在提示订户购买之前可以免费使用内容的次数。
`uniqueId`	`字符串`	订户的唯一 ID。
`url`	`字符串`	发送给订户的消息中要包含的 URL。
`usageCount`	`整型`	每一次购买所允许使用的次数。
`usagePrice`	`双精度型`	每次使用或多次使用支付的价格。
`userAgent`	`字符串`	设备的用户代理。该字符串是在 HTTP 头中返回的确切字符串。
`userAgentPattern`	`字符串`	设备的用户代理。该字符串是一个正则表达式，是可以匹配各种文本字符串的模式。
`userGuideUrl`	`字符串`	指向该内容用户指南的 URL。
`username`	`字符串`	订户的用户名。
`version`	字符串	内容的版本。
`wapPreviews`	`向量`，preview 类型的元素	针对 WAP 浏览器的预览文件列表。如果没有针对 WAP 浏览器的预览文件，则返回空列表。
`wasDelivered`	`布尔型`	表示是否使用 SMS 将内容发送到设备的标志。`True` 表示使用 SMS。`False` 表示不使用 SMS。
`webPreviews`	`向量`，preview 类型的元素	针对 Web 浏览器的预览文件列表。如果没有针对 Web 浏览器的预览文件，则返回空列表。

11.3.3 使用处理程序的示例

本节提供两个使用订户 API 的 XML-RPC 实现的示例。

11.3.3.1 API 上下文对象创建示例

以下节选代码说明了如何创建 API 上下文对象。该样例使用 Java 编程语言的绑定。

编码样例 11-3 使用 XML-RPC 创建 API 上下文对象
... // 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 使用 XML-RPC 创建 API 上下文对象

...
// 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 创建处理程序以及购买内容的示例

以下节选代码显示如何创建处理程序以及使用该处理程序购买内容。该样例使用 Java 编程语言的绑定。

编码样例 11-4 创建处理程序
... // 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 ... } ...

编码样例 11-4 创建处理程序

...
// 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 (表格注解) 除了列出的对象，所有方法均返回 response_code；如果发生错误则返回 response_message。}

^{2 (表格注解) 除了列出的对象，所有方法均返回 response_code；如果发生错误则返回 response_message。}

^{3 (表格注解) 该方法更改内存中保留的类别列表。要永久更改，必须调用 updateCategories。}

^{4 (表格注解) 除了列出的对象，所有方法均返回 response_code；如果发生错误则返回 response_message。}

^{5 (表格注解) 除了列出的对象，所有方法均返回 response_code；如果发生错误则返回 response_message。}

^{6 (表格注解) 除了列出的对象，所有方法均返回 response_code；如果发生错误则返回 response_message。}

^{7 (表格注解) 除了列出的对象，所有方法均返回 response_code；如果发生错误则返回 response_message。}

^{8 (表格注解) 除了列出的对象，所有方法均返回 response_code；如果发生错误则返回 response_message。}

^{9 (表格注解) 除了列出的对象，所有方法均返回 response_code；如果发生错误则返回 response_message。}

^{10 (表格注解) 除了列出的对象，所有方法均返回 response_code；如果发生错误则返回 response_message。}

11

订户 API

11.1 一般处理流程

11.2 使用订户 API

11.2.1 管理事务

11.2.2 IApiContext 对象创建示例

11.2.3 创建服务的示例

11.3 XML-RPC 实现

11.3.1 访问 Content Delivery Server

11.3.2 使用订户 API 的 XML-RPC 处理程序

11.3.2.1 XML-RPC 方法调用的指导

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