Cisco SCMS SCE Subscriber API Programmer's Guide

The SCMS SCE Subscriber API distribution is part of the SCMS SM-LEG distribution file and is located in the sce_api directory.

The SCMS SCE Subscriber API is packaged in a UNIX tar file. You can extract the SCMS SCE Subscriber API using the UNIX tar utility or most Windows compression utilities.

The API connects to the PRPC server on the SCE platform. The PRPC server is a server running a proprietary RPC protocol designed by Cisco. For more information, see the SCE User Guide.

Before using the API, ensure that:

To enable the SCE platform to issue a request for subscriber information when running in a Pull Model (see Pull Model), configure the following using the SCE platform Command-Line Interface (CLI):

For more information about configuring the SCE platform, see the SCE 1000 or SCE 2000 User Guides.

To enable the RDR formatter to issue quota-related indications, configure the RDR formatter on the SCE platform as follows:

#>RDR-formatter destination 127.0.0.1 port 33001 category number 4 priority 100

By default, Quota RDRs tags are mapped to category 4. If another category is required, use the following CLI command:

#>RDR-formatter rdr-mapping add tag-ID <tag number> category-number <number>

To enable the API to receive Quota indications, the RDR server should be enabled and listening on the same port that is configured in the RDR formatter. To verify the RDR server configuration, use the following CLI:

#>show RDR-server RDR server is ONLINE RDR server port is 33001

Use the following CLI to enable the RDR server:

#>configure (config)#>RDR-server Default RDR server port is 33001

Use the following CLI to change the RDR server port:

#>configure (config)#>RDR-server port <port>

The SCE platform allows setting the timeout for the API to reconnect to the SCE platform after it was disconnected. During this timeout, the SCE will not free the resources and no data will be lost. After the timeout has elapsed and the API did not reconnect, the SCE considers the API disconnected and frees all the resources. The default timeout value is 5 minutes.

Use the following CLI command to configure the timeout:

(config)# management-agent sce-api timeout <timeout-in-sec>

Use the following CLI command to reset the timeout to the default value:

(config)# default management-agent sce-api timeout

Use the following CLI command to view the timeout value:

# show management-agent sce-api

Subscriber ID is a subscriber unique identifier, for example, a user name, IMSI (International Mobile Subscriber Identity), or other codes that uniquely identify a subscriber.

When working in the Pull Model integration, the SCE assigns each unknown subscriber IP address with a temporary Subscriber ID, Anonymous Subscriber ID, until it receives the real Subscriber ID from the Policy Server.

For more information on the Pull Model integration, see the Subscriber Integration Models section.

The SCE correlates a certain traffic flow to a subscriber by mapping a network identifier, for example, IP address, IP range, or VLAN, to the subscriber entity.

A Policy Profile includes a set of parameters used by the SCA BB solution to define what policy is enforced on the subscriber.

A quota includes the quota-bucket values of the service quota or quotas available for the usage of the subscriber.

In push model integration, an external server introduces (pushes) the subscribers to the SCE platform. This is performed whenever a new subscriber logs in to the network or the external server presumes to know all subscribers and introduces them to the SCE box when they connect.

In pull model integration, the SCE platform requests subscriber data from the external entity when it encounters traffic of an unknown subscriber, known as an anonymous subscriber. The external entity retrieves the required subscriber information and sends it back to the SCE platform.

The string format of an IP address is the commonly used decimal notation: IP-Address=[0-255].[0-255].[0-255].[0-255]

Example:

The string format of an IP range is an IP address in decimal notation and a decimal specifying the number of 1s in a bit mask: IP-Range=[0-255].[0-255].[0-255].[0-255]/[0-32].

Examples:

The string format for VLAN tag mapping is a decimal number in the following range: [2-2046]

The com.scms.common.NetworkID class provides the VLAN mapping type:

Construct NetworkID with a single IP address:

Construct NetworkID with a range of IP addresses:

NetworkID nid = new NetworkID(“1.1.1.1/24”,NetworkID.TYPE_IP)

Construct NetworkID with multiple IP addresses:

NetworkID nid = new NetworkID(new String[]{“1.1.1.1”,”2.2.2.2”,”3.3.3.3”},
				        NetworkID.ALL_IP_MAPPINGS)
Construct NetworkID with a single VLAN address:
NetworkID nid = new NetworkID(“23”,NetworkID.TYPE_VLAN)

The API provides a PolicyProfile class to format subscriber policy profiles required for the API operations.

The following method constructs the PolicyProfile class based on the array of policy properties:

public PolicyProfile(String[] policy)

The following method allows adding a policy property to the profile according to the format described above:

PolicyProfile pp = new PolicyProfile(new String[]{"packageId=22",
                                                  "monitor=1"})

The SCAS_BB_Quota class implements the Quota interface, which the QuotaListenerEx interface uses in all callback functions.

The following method constructs the SCAS_BB_Quota based on the array of IDs and values:

The following method constructs the SCAS_BB_Quota based on the array of IDs and values, the profile ID, the reason, and the timestamp:

The following method allows retrieving of the quota buckets' IDs:

public long[] getBucketValues()

public int getQuotaProfileId()

public int getReason()

public long getTimestamp()

The SCAS_BB_QuotaOperation class implements the QuotaOperation interface, which is used for Subscriber Provisioning operations that include the subscriber's quota such as login operation (see the login operation section) and update quota operation (see the quotaUpdate operation).

The following method constructs the SCAS_BB_QuotaOperation based on the array of IDs, values and actions:

The following method allows retrieving of the quota buckets' IDs:

public long[] getBucketValues()

public short[] getBucketActions()

The BulkBase class provides an iterator to view the data contained in the bulk.

The following is the syntax for the Bulk Iterator:

Iterator getIterator()

This iterator can be used for iteration over the bulks received from the SCE in various indications (for example, logoutBulkIndication, loginPullBulkResponseIndication, and so forth) or for inspecting the data you provided to various operations in case an operation has failed.

The iterator provides the following methods for data retrieval:

public Object next()
public boolean hasNext()
The next() method returns a SubscriberData object.
The SubscriberData class is used for retrieving the information of a single subscriber contained within the bulk.
SubscriberData
The SubscriberData class represents all of the operations that can be performed on a specific subscriber. The SubscriberData class contains the following utility methods for information retrieval:
public String getSubscriberID()
public String getAnonymousID()
public String[] getMappings()
public short[] getTypes()
public boolean getAdditiveFlag()
public String[] getPolicyStrings()
public String[] getQuotaStrings()
public String[] getQuotaOperationStrings()
The following sections describe various bulk data types that are available for different API operations.

This class represents bulk of subscribers and it includes all data required for the loginBulk operation.

public void addBulkEntry(String subscriberID,
                         NetworkID networkID,
                         boolean networkIdsAdditive,
                         PolicyProfile policy,
                         QuotaOperation quota)
Parameters
subscriberID—The unique ID of the subscriber. See the Subscriber ID section for the subscriber ID format description.
networkID—The network identifier of the subscriber. See the Network ID Mappings section for more information.
networkIDAdditive—If this flag is set to TRUE, the supplied NetworkID is added to the existing networkIDs of the subscriber. Otherwise, the supplied networkID replaces the existing networkIDs.
policy—Policy profile of the subscriber. See the SCA BB Subscriber Policy Profile section for more information.
quota—Quota of the subscriber. See the Subscriber Quota section for more information.

The logoutBulkIndication callback function that requires only subscriber IDs to be entered uses the SubscriberID_BULK class. See logoutBulkIndication callback method.

public SubscriberID_BULK()

addBulkEntry(String subscriberID)

Use the NetworkAndSubscriberID_BULK class in bulk operations that require Subscriber IDs and NetworkIDs in the following operations:

public NetworkAndSubscriberID_BULK(String[] subscriberIDs,
                                   NetworkID[] networkIDs,
                                   boolean[] netIdAdditive)
To construct an empty NetworkAndSubscriberID_BULK, use the following method:
public NetworkAndSubscriberID_BULK()

addBulkEntry(String subscriberID,
             NetworkID networkID,
             boolean netIdAdditive)
Parameters
subscriberID—The unique ID of the subscriber. See the Subscriber ID section for more information.
networkID—The network identifier of the subscriber. See the Network ID Mappings section for more information.
networkIDAdditive—If this flag is set to TRUE, the supplied NetworkID is added to the existing networkIDs of the subscriber. Otherwise, the supplied networkID replaces the existing networkIDs.

This class represents a bulk of subscribers and includes all data required for the loginPullResponseBulk method.

public addBulkEntry(String anonymousSubscriberID,
                    String subscriberID,
                    NetworkID networkID,
                    boolean networkIdAdditive,
                    PolicyProfile policy,
                    QuotaOperation quota)
Parameters
anonymousSubscriberID—The identifier of the anonymous subscriber. This is sent by the SCE within the loginPullRequest/loginPullBulkRequest indication. See the Subscriber Integration Models section for more information.
subscriberID—The unique ID of the subscriber. See the Subscriber ID section for more information.
networkID—The network identifier of the subscriber. See the Network ID Mappings section for more information.
networkIDAdditive—If this flag is set to TRUE, the supplied NetworkID is added to the existing networkIDs of the subscriber. Otherwise, the supplied networkID replaces the existing networkIDs.
policy—The policy profile of the subscriber. See the SCA BB Subscriber Policy Profile section for more information.
quota—The quota of the subscriber. See the Subscriber Quota section for more information.

The updatePolicyProfileBulk operation uses this class that represents a bulk of subscriber IDs and subscriber policy profiles.

public PolicyProfile_BULK()

public addBulkEntry(String subscriberID,  PolicyProfile policy)

The following operations use this class that represents a bulk of subscribers IDs and subscriber quota buckets:

public Quota_BULK(String[] subscriberIDs, Quota[] subscribersQuota)

public Quota_BULK()

public addBulkEntry(String subscriberID,Quota quota)

The QuotaUpdateBulk operation and the login operation use this class that represents a bulk of subscribers IDs and subscriber Quota operations.

public QuotaOperation_BULK(String[] subscriberIDs,
                           QuotaOperation[]quotaOperations)
To construct an empty QuotaOperation_BULK, use the following method:
public QuotaOperation_BULK()

addBulkEntry(String subscriberID, QuotaOperation quotaOperation)

com.scms.common package contains all data types used by the API.

As described in previous sections, many of the API operations are based on callback methods. The user provides a “listener”, which is called when certain events occur. The following warning defines the main guideline for programming with callback methods.

This caution applies to the following operations:

The PRPC_SCESubscriberAPI provides the following constructors:

Syntax:

public PRPC_SCESubscriberApi(String apiName, String sceHost)
                                             throws UnknownHostException

public PRPC_SCESubscriberApi(String apiName,
                             String sceHost,
                             long autoReconnectInterval)
                                             throws UnknownHostException

public PRPC_SCESubscriberApi(String apiName,
                             String sceHost,
                             int scePort,
                             long autoReconnectInterval)
                                             throws UnknownHostException
Parameters:
The following is a description of the constructor arguments for the API constructors:
apiName—Specifies an API name.
Note
 The API name should be unique per SCE. If you construct more than one API with the same name and connect it to a single SCE, the SCE platform will handle the APIs as one API client. Use this feature only when high-availability is supported. For more information about high availability, see the Implementing High Availability section.
sceHost—Can be either an IP address or a reachable hostname.
scePort—PRPC protocol TCP port to connect to the SCE (default value is 14374)
autoReconnectInterval—Defines the interval (in milliseconds) for attempting reconnection by the reconnection task, as follows:
If the value is 0 or less, the reconnection task is not activated (no auto-reconnect is attempted).
If the value is greater than 0 and a connection failure exists, the reconnection task will be activated every <autoReconnectInterval> milliseconds.
Default value: -1 (no auto-reconnect is attempted)
Note
To enable the auto-reconnect support, the connect method of the API must be called at least once.
Examples:
The following code constructs an API with an auto-reconnection interval of 10 seconds:
PRPC_SCESuscriberAPI sceApi = new PRPC_SCESuscriberAPI(“MyApi”,
                                                       ”10.1.1.1”,
                                                        10000);
sceApi.connect();
The following code constructs an API without auto-reconnection support:
PRPC_SCESuscriberAPI sceApi = new PRPC_SCESuscriberAPI(“MyApi”,
                                                       ”10.1.1.1”);
sceApi.connect();
Listeners Setup Operations
After initializing the API, it should be set-up with the utilized listeners based on the type of application using the API, and the topology used. For more information about topologies, see the Supported Topologies sections.
The listeners setup operations may include:
Setting a connection listener, described in more detail in the ConnectionListener Interface section:
public void setConnectionListener(ConnectionListener listener)

public void registerLoginPullListener(LoginPullListener listener)

public void registerLogoutListener(LogoutListener listener)

public void registerQuotaListener(QuotaListener listener)

The syntax for the init method is as follows:

public void init(Properties properties)

The following code shows how to customize properties during initialization:

// API construction
PRPC_SCESuscriberAPI sceApi = new PRPC_SCESuscriberAPI(“MyApi”,
                                                       “10.1.1.1”,10000);
// API initialization
java.util.Properties p = new java.util.Properties();
p.setProperty("prpc.client.output.machinemode.recordnum", 2048+"");

api.init(p);

// connect to the API
sceApi.connect();
Note
The init method is called before the connect method.

public String getApiVersion()

This method queries the API version. Version is a string formatted as <Major Version.Minor Version>.