Cisco SCMS SM C/C++ API Programmer's Guide

The login method adds or modifies a domain, mappings, and properties of a subscriber that already exists in the SM database. It can be called with partial data; for example, with only mappings or only properties provided and NULL put in the unchanged fields.

If another subscriber with the same (or colliding) mappings already exists in the same domain, the colliding mappings will be removed from the other subscriber and assigned to the new subscriber.

If the subscriber does not exist in the SM database, it will be created with the data provided.

argName—See explanation of subscriber name format.

argMappings—See explanation of mappings and mapping types. If no mappings are specified, and the argIsAdditive flag is TRUE, the previous mappings will be retained. If no such mappings exist, the operation will fail.

argMappingTypes—See explanation of mappings and mapping types.

argMappingsSize—The size of the argMappings and argMappingTypes arrays.

argPropertyKeys—See explanation of property keys and values in the General API Concepts chapter.

argPropertyValues—See explanation of property keys and values in the General API Concepts chapter.

argPropertySize—The size of the argPropertyKeys and argPropertyValues arrays.

argDomain—See explanation of domains. If domain is NULL, but the subscriber already has a domain, the existing domain will be retained.

ArgIsAdditive—Refers to the mappings parameters.

argAutoLogoutTime—Applies only to mappings provided as arguments to this method.

A pointer to a ReturnCode structure with a void type, unless an error has occurred.

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

To add the IP address 192.168.12.5 to an existing subscriber named john without affecting existing mappings:

To add the IP address 192.168.12.5 overriding previous mappings:

To extend the auto logout time of 192.168.12.5 that was previously assigned to john:

To modify a dynamic property of john (e.g. package ID):

To add the IP address 192.168.12.5 to an existing subscriber named john without affecting existing mappings and modify a dynamic property of john (e.g. package ID):

Locates the subscriber in the database and removes mappings from the subscriber.

argName—See explanation of subscriber name format.

argMappings—See explanation of mappings and mapping types. If no mappings are specified, all the subscriber mappings will be removed.

argMappingTypes—See explanation of mappings and mapping types.

argMappingsSize—The size of the argMappings and argMappingTypes arrays.

A pointer to a ReturnCode structure with a Boolean type:

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

To remove IP address 192.168.12.5 from subscriber john:

Locates the subscriber in the database according to the specified domain and removes mappings from the subscriber.

argName—See explanation of subscriber name format.

argMappings—See explanation of mappings and mapping types. If no mappings are specified, all the subscriber mappings will be removed.

argMappingTypes—See explanation of mappings and mapping types.

argMappingsSize—The size of the argMappings and argMappingTypes arrays.

argDomain—See explanation of domains. The operation will fail if either of the following conditions exists:

A pointer to a ReturnCode structure with a Boolean type:

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

To remove IP address 192.168.12.5 of subscriber john from domain subscribers:

Locates a subscriber based on domain and mapping, and removes the subscriber mappings. The subscriber remains in the database.

argMapping—See explanation of mappings and mapping types.

argMappingType—See explanation of mappings and mapping types.

argDomain—See description in logoutByNameFromDomain operation.

A pointer to a ReturnCode structure with a Boolean type:

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

To remove IP address 192.168.12.5 from domain subscribers:

A login method adapted for the cable environment, which calls the cable support module in the SM. This method logs in CPEs to the SM. To log in a CM, specify the CM MAC address in both CPE and CM arguments. For additional information, see the Cable Environment Appendix of the Cisco SCMS Subscriber Manager User Guide.

argCpe—A unique identifier of the CPE (usually a MAC address).

argCm—A unique identifier of the cable modem (usually a MAC address).

argIp—The CPE IP address.

argLease—The CPE lease time.

argDomain—See explanation of domains. The domain will usually be CMTS IP.

argPropertyKeys—See explanation of the keys and values of the Subscriber Properties. If the CPE is provided with partial or no application properties, the values for the missing application properties will be copied from the application properties of the CM to which this CPE belongs. Each CM application property thus serves as a default for the CPE under it.

argPropertyValues—See explanation of the keys and values of the Subscriber Properties.

argPropertySize—The size of the argPropertyKeys and argPropertyValues arrays.

A pointer to a ReturnCode structure with a void type.

None

To add the IP address 192.168.12.5 to a CM called CM1 with 2 hours lease time:

To add the IP address 192.168.12.50 to a CPE called CPE1 behind CM1 with a lease time of 1 hour:

Indicates a logout (CPE becoming offline) event to the SM cable support module.

argCpe—See description in the loginCable method.

argCm—See description in the loginCable method.

argIp—See description in the loginCable method.

argDomain—See description in the loginCable method.

A pointer to a ReturnCode structure with a Boolean type:

None

To remove the IP address 192.168.12.5 from CPE1 that is behind CM1:

Creates a new subscriber record according to the given data and adds it to the SM database. If a subscriber by this name already exists, it will be removed before the new one is added. In contrast to login, which modifies fields passed to it and leaves unspecified fields unchanged, addSubscriber sets the subscriber exactly as specified by the parameters passed to it.

Example:

Subscriber AB, already set up in the subscriber database, has a single IP mapping of IP1.

If an addSubscriber operation for AB is called with no mappings specified (NULL in both the mappings and mappingTypes fields), AB will be left with no mappings.

However, calling a login operation with these NULL-value parameters will not change AB's mappings; AB will still have its previous IP mapping of IP1.

argName—See explanation of subscriber name format.

argMappings—See explanation of mappings and mapping types.

argMappingTypes—See explanation of mappings and mapping types in the General API Concepts chapter.

argMappingsSize—The size of the argMappings and argMappingTypes arrays.

argPropertyKeys—See explanation of property keys and values in the General API Concepts chapter.

argPropertyValues—See explanation of property keys and values in the General API Concepts chapter.

argPropertySize—The size of the argPropertyKeys and argPropertyValues arrays.

argCustomPropertyKeys—See explanation of custom property keys and values in the General API Concepts chapter.

argCustomPropertyValues—See explanation of custom property keys and values in the General API Concepts chapter.

argPropertySize—The size of the argCustomPropertyKeys and argCustomPropertyValues arrays.

argDomain—See explanation of domains. A NULL value indicates that the subscriber is domain-less.

A pointer to a ReturnCode structure with a void type.

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

To add a new subscriber, john, with custom properties:

Removes a subscriber completely from the SM database.

argName—See explanation of Subscriber Name Format.

A pointer to a ReturnCode structure with a Boolean type:

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

To remove subscriber john entirely from the database:

bapi.removeSubscriber(“john”);

ReturnCode* removeAllSubscribers()

Removes all subscribers from the SM, leaving the database with no subscribers.

A pointer to a ReturnCode structure with a void type.

None.

ReturnCode* getNumberOfSubscribers()

Retrieves the total number of subscribers in the SM database.

A pointer to a ReturnCode structure holding an integer describing the number of subscribers in the SM.

None

ReturnCode* getNumberOfSubscribersInDomain(char* argDomain)

Retrieves the number of subscribers in a subscriber domain.

argDomain—A name of a subscriber domain that exists in the SM's domain repository.

A pointer to a ReturnCode structure holding an integer describing the number of subscribers in the domain provided.

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

ReturnCode* getSubscriber(char* argName)

Retrieves a subscriber record. Each field is formatted as an integer, string, or string array, as described in the Return Value section for this method. If the subscriber does not exist in the SM database, an exception will be thrown.

argName—See explanation of subscriber name format.

A pointer to a ReturnCode structure holding an array of ReturnCode structures with nine elements. No array element is NULL.

The following list is the element values and their meanings:

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

To retrieve the subscriber record of john:

ReturnCode* subscriberExists(char* argName)

Verifies that a subscriber exists in the SM database.

argName—See explanation of subscriber name format.

A pointer to a ReturnCode structure with a Boolean type:

None.

ReturnCode* subscriberLoggedIn(char* argName)

Checks whether a subscriber that already exists in the SM database is logged in; i.e., if the subscriber also exists in an SCE database.

When the SM is configured to work in Pull mode, a TRUE value returned by this method does not guarantee that the subscriber actually exists in an SCE database, but rather that the subscriber is available to be pulled by an SCE if needed.

If the subscriber does not exist in the SM database, an exception will be thrown.

argName—See explanation of subscriber name format.

A pointer to a ReturnCode structure with a Boolean type:

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

ReturnCode* getSubscriberNameByMapping(	char* argMapping,
							MappingType argMappingType,
							char* argDomain)

Finds a subscriber name according to a mapping and a domain.

argMapping—See explanation of mappings and mapping types.

argMappingType—See explanation of mappings and mapping types.

argDomain—The name of the domain to which the subscriber belongs. The operation will fail if either of the following conditions exists:

A pointer to a ReturnCode structure with a String (char*) type:

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

Gets a bulk of subscriber names from the SM database, starting with argFirstName followed by the next argAmount subscribers (in alphabetical order).

If argFirstName is NULL, the (alphabetically) first subscriber name that exists in the SM database will be used.

argFirstName—Last subscriber name from last bulk (first name to look for). Use NULL to start with the first (alphabetic) subscriber.

argAmount—Limit on number of subscribers that will be returned. If this value is higher than the SM limit (1000), the SM limit will be used.

A pointer to a ReturnCode structure with a String Array (char**) holding a list of subscriber names ordered alphabetically.

The method will return as many subscribers as are found in the SM database, starting at the requested subscriber. The lower value of argAmount and the SM limit (1000) limits the array size.

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

To receive an alphabetical list of subscriber names:

ReturnCode* getSubscriberNamesInDomain( char* argFirstName,
						    int argAmount,
						    char* argDomain)

Retrieves subscribers from the SM database that are associated with the specified domain.

The function of this operation is the same as the getSusbcriberNames operation.

argFirstName—See description in getSusbcriberNames operation.

argAmount—See description in getSusbcriberNames operation.

argDomain—The name of a subscriber domain that exists in the SM domain repository.

An alphabetically ordered array of subscriber names that belong to the specified domain.

See the Return Value section of the getSusbcriberNames operation for more information.

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

Retrieves subscribers from the SM database whose names begin with a specified prefix.

The function of this operation is the same as the getSusbcriberNames operation.

argFirstName—See description in getSusbcriberNames operation.

argAmount—See description in getSusbcriberNames operation.

argPrefix—A case-sensitive string that marks the prefix of the required subscriber names.

An alphabetically ordered array of subscriber names that start with the prefix required.

See the Return Value section of the getSusbcriberNames operation.

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

Retrieves subscribers from the SM database whose names end with the specified suffix.

The functions of this operation are the same as the getSusbcriberNames operation.

argFirstName—See description in getSusbcriberNames operation.

argAmount—See description in getSusbcriberNames operation.

argSuffix—A case-sensitive string that marks the suffix of the required subscriber names.

An alphabetically ordered array of subscriber names that end with the suffix required.

See the Return Value section of the getSubscriberNames operation.

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

Provides a list of current subscriber domains in the SM domain repository.

A pointer to a ReturnCode structure with a String Array (char**) holding a complete list of subscriber domain names in the SM.

None

ReturnCode* setPropertiesToDefault(	char* argName,
					      char** argPropertyKeys,
					      int argPropertySize)

Resets the specified application properties of a subscriber. If an application is installed, the relevant application properties will be set to the default value of the properties according to the currently loaded application information. If an application is not installed, an ERROR_CODE_ILLEGAL_STATE error code is returned.

argName—See explanation of subscriber name format.

argPropertyKeys—See explanation of property keys and values in the General API Concepts chapter.

argPropertySize—The size of the argPropertyKeys array.

A pointer to a ReturnCode structure with a void type.

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

Resets the specified custom properties of a subscriber.

argName—See explanation of subscriber name format.

argCustomPropertyKeys—See explanation of custom property keys and values in the General API Concepts chapter.

argCustomPropertySize—The size of the argCustomPropertyKeys array.

A pointer to a ReturnCode structure with a void type.

The following is the list of error codes that this method might return:

For a description of error codes, see List of Error Codes.

Sets an implementation of the abstract Logger class. Use this method to integrate the SM API log messages with the host application log.

argLogger—An implementation of the abstract Logger class.

None.

Bool init(	int argSupportedThreads,
		int argThreadPriority,
		Uint32 argBufferSize,
		Uint32 argKeepAliveDuration,
		Uint32 argConnectionTimeout,
		Uint32 argReconnectTimeout)

Configures and initializes the API.

argSupportedThreads—The number of threads the API should support.

argThreadPriority—The priority for the PRPC protocol network thread.

argBufferSize—The internal buffer size (for default use 2000000 (2,000,000) bytes).

argKeepAliveDuration—A hint regarding the wanted delay between PRPC protocol keep-alive messages (default use 10 seconds).

argConnectionTimeout—A hint regarding the wanted timeout on a non-responding PRPC protocol connection (for default use 20 seconds).

argReconnectTimeout—When the connection to the SM is down, the API will attempt to re-establish the connection after this timeout.

Boolean value:

Allocates, configures, and initializes the API.

argSupportedThreads—The number of threads the API should support.

argThreadPriority—The priority for the PRPC protocol network thread.

argBufferSize—The internal buffer size (default use 2000000 (2,000,000) bytes).

argKeepAliveDuration—A hint regarding the wanted delay between PRPC protocol keep-alive messages (default use 10 seconds).

argConnectionTimeout—A hint regarding the wanted timeout on a non-responding PRPC protocol connection (for default use 20 seconds).

SMB_HANDLE handle to the API. If the handle equals NULL, the initialization failed. Otherwise, a non-NULL value is returned.

Releases the resources used by the API. This function must be called at the end of the use of the API.

argApiHandle—The API handle received using the SMB_init function.

None.

void setReconnectTimeout(Uint32 reconnectTimeout)

Sets the reconnection timeout.

When the connection to the SM is down, the API will attempt to re-establish the connection after 'reconnection timeout' seconds.

reconnectTimeout—The timeout.

None.

void setName(char *argName)

Sets the name of the API, which serves as a unique identifier for the API-SM connection. The setName function should be called before calling the connect method.

argName—The API name.

None.

bool connect(char* argHostName, Uint16 argPort = 14374)

Attempts to establish a PRPC protocol connection to the SM.

argHostName—The SM IP-Address or hostname.

argPort—TCP port to connect the SM on (default is 14374).

Boolean value:

bool disconnect()

Attempts to terminate the PRPC protocol connection to the SM.

Boolean value:

bool isConnected();

Checks whether the PRPC protocol connection to the SM is up and running.

Boolean value: