Cisco Service Control Subscriber Manager C/C++ API ... · 3 Cisco Service Control Subscriber...

Cisco Service Control Subscriber Manager C/C++ API Programmer GuideRelease 5.0.xJuly 30, 2014

Cisco Systems, Inc.www.cisco.com

Cisco has more than 200 offices worldwide. Addresses, phone numbers, and fax numbers are listed on the Cisco website at www.cisco.com/go/offices.

Text Part Number: OL-31824-01

http://www.cisco.com

http://www.cisco.com/go/offices

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS” WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

Cisco Service Control Subscriber Manager C/C++ API Programmer Guide© 2014 Cisco Systems, Inc. All rights reserved.

http://www.cisco.com/go/trademarks

OL-31824-01

C O N T E N T S

Introduction 1

Document Revision History 1

Organization 2

Related Documentation 2

Conventions 2

Obtaining Documentation and Submitting a Service Request 3

3

C H A P T E R 1 Getting Started 1-1

Introduction 1-1

Platforms and Compilers 1-1

Installation Package Contents 1-1

Installing the Cisco Service Control Subscriber Manager C/C++ API 1-2

Installing the Cisco Service Control Subscriber Manager LEG on a UNIX Platform 1-3

Installing the Cisco Service Control Subscriber Manager LEG on a Windows Platform 1-3

Compiling and Running the Cisco Service Control Subscriber Manager C/C++ API 1-3

Compiling and Running a Program on Windows 1-3

Example Using Microsoft Visual C++ 6.0 1-4

Compiling and Running a Program on Solaris 1-4

Compiling and Running a Program on Linux 1-5

C H A P T E R 2 General API Concepts 2-1

Introduction 2-1

Blocking API and Nonblocking API 2-1

Blocking API 2-2

Nonblocking API 2-2

Reliability 2-2

C API Versus C++ API 2-2

Method Names 2-3

Handle Pointers 2-3

Blocking API—Example 2-3

Nonblocking API—Example 2-3

API Initialization 2-4

3Cisco Service Control Subscriber Manager C/C++ API Programmer Guide

Contents

Constructing the API 2-4

Setting the LEG Name 2-4

Performing Setup Operations 2-5

Blocking API Setup 2-5

Nonblocking API Setup 2-5

Connecting to the Cisco Service Control Subscriber Manager 2-5

API Finalization 2-5

ReturnCode Structure 2-6

Definition 2-6

Return Code Structure Example 2-6

ErrorCode Structure 2-7

Definition 2-7

Subscriber Name Format 2-7

Network ID Mappings 2-7

Specifying IP Address Mapping 2-8

Specifying IP Range Mapping 2-8

Specifying Private IP Address or Private IP Range over VPN Mapping 2-9

Specifying VLAN Tag Mapping 2-9

Specifying IPv6 Address Mapping 2-9

Subscriber Domains 2-9

Subscriber Properties 2-10

Custom Properties 2-10

Logging Capabilities 2-10

Disconnect Callback Listener 2-11

Disconnect Callback Listener Example 2-11

Signal Handling 2-11

Practical Tips 2-12

C H A P T E R 3 Blocking API 3-1

Introduction 3-1

Multithreading Support 3-1

Multithreading Support Example 3-1

Operation Timeout Error Code 3-2

Blocking API Methods 3-2

login 3-4

Syntax 3-4

Description 3-4

Parameters 3-5


OL-31824-01

Contents

Return Value 3-5

Error Codes 3-5

Example 3-6

logoutByName 3-8

Syntax 3-8

Description 3-9

Parameters 3-9

Return Value 3-9

Error Codes 3-9

Example 3-9

logoutByNameFromDomain 3-10

Syntax 3-10

Description 3-10

Parameters 3-10

Return Value 3-11

Error Codes 3-11

Example 3-11

logoutByMapping 3-12

Syntax 3-12

Description 3-12

Parameters 3-12

Return Value 3-12

Error Codes 3-13

Example 3-13

loginCable 3-13

Syntax 3-13

Description 3-14

Parameters 3-14

Return Value 3-14

Error Codes 3-14

Example 3-14

logoutCable 3-15

Syntax 3-15

Description 3-15

Parameters 3-15

Return Value 3-16

Error Codes 3-16

Example 3-16

addSubscriber 3-16

Syntax 3-16


OL-31824-01

Contents

Description 3-17

Parameters 3-17

Return Value 3-17

Error Codes 3-18

Example 3-18

removeSubscriber 3-18

Syntax 3-19

Description 3-19

Parameters 3-19

Return Value 3-19

Error Codes 3-19

Example 3-19

removeAllSubscribers 3-19

Syntax 3-20

Description 3-20

Return Value 3-20

Error Codes 3-20

getNumberOfSubscribers 3-20

Syntax 3-20

Description 3-20

Return Value 3-20

Error Codes 3-21

getNumberOfSubscribersInDomain 3-21

Syntax 3-21

Description 3-21

Parameters 3-21

Return Value 3-21

Error Codes 3-21

getSubscriber 3-22

Syntax 3-22

Description 3-22

Parameters 3-22

Return Value 3-22

Error Codes 3-23

Example 3-23

subscriberExists 3-23

Syntax 3-24

Description 3-24

Parameters 3-24

Return Value 3-24


OL-31824-01

Contents

Error Codes 3-24

subscriberLoggedIn 3-24

Syntax 3-24

Description 3-24

Parameters 3-25

Return Value 3-25

Error Codes 3-25

getSubscriberNameByMapping 3-25

Syntax 3-25

Description 3-25

Parameters 3-26

Return Value 3-26

Error Codes 3-26

getSubscriberNames (all) 3-26

Syntax 3-26

Description 3-27

Parameters 3-27

Return Value 3-27

Error Codes 3-27

Example 3-27

getSubscriberNames (filter by property) 3-28

Syntax 3-28

Description 3-28

Parameters 3-29

Return Value 3-29

Error Codes 3-29

getSubscriberNamesInDomain 3-29

Syntax 3-30

Description 3-30

Parameters 3-30

Return Value 3-30

Error Codes 3-30

getSubscriberNamesWithPrefix 3-31

Syntax 3-31

Description 3-31

Parameters 3-31

Return Value 3-31

Error Codes 3-31

getSubscriberNamesWithSuffix 3-32

Syntax 3-32


OL-31824-01

Contents

Description 3-32

Parameters 3-32

Return Value 3-32

Error Codes 3-32

getDomains 3-33

Syntax 3-33

Description 3-33

Return Value 3-33

Error Codes 3-33

setPropertiesToDefault 3-33

Syntax 3-33

Description 3-34

Parameters 3-34

Return Value 3-34

Error Codes 3-34

removeCustomProperties 3-34

Syntax 3-34

Description 3-34

Parameters 3-35

Return Value 3-35

Error Codes 3-35

C++ setLogger Method 3-35

Syntax 3-35

Description 3-35

Parameters 3-35

Return Value 3-35

C++ init Method 3-36

Syntax 3-36

Description 3-36

Parameters 3-36

Return Value 3-36

Example 3-37

C SMB_init Function 3-37

Syntax 3-37

Description 3-37

Parameters 3-37

Return Value 3-38

Example 3-38

C SMB_release Function 3-38

Syntax 3-38


OL-31824-01

Contents

Description 3-38

Parameters 3-38

Return Value 3-38

setReconnectTimeout 3-38

Syntax 3-39

Description 3-39

Parameters 3-39

Return Value 3-39

setName 3-39

Syntax 3-39

Description 3-39

Parameters 3-39

Return Value 3-40

connect 3-40

Syntax 3-40

Description 3-40

Parameters 3-40

Return Value 3-40

disconnect 3-40

Syntax 3-41

Description 3-41

Return Value 3-41

isConnected 3-41

Syntax 3-41

Description 3-41

Return Value 3-41

Blocking API C++ Code Examples 3-42

Getting Number of Subscribers 3-42

Adding a Subscriber, Printing Information, and Removing a Subscriber 3-43

Blocking API C Code Examples 3-45

Getting Number of Subscribers 3-45

Adding a Subscriber, Printing Information, and Removing a Subscriber 3-46

C H A P T E R 4 Nonblocking API 4-1

Introduction 4-1

Multithreading Support 4-1

Result Handler Callbacks 4-1

Result Handler Callbacks Example 4-2

Nonblocking API Methods 4-3


OL-31824-01

Contents

login 4-4

Syntax 4-4

logoutByName 4-4

Syntax 4-4

logoutByNameFromDomain 4-4

Syntax 4-4

logoutByMapping 4-5

Syntax 4-5

loginCable 4-5

Syntax 4-5

logoutCable 4-5

Syntax 4-5

C++ setLogger Method 4-6

Syntax 4-6

C++ init Method 4-6

Syntax 4-6

C SMNB_init Function 4-6

Syntax 4-6

Return Value 4-7

C SMNB_release Function 4-7

Syntax 4-7

setReconnectTimeout 4-7

Syntax 4-7

setName 4-7

Syntax 4-7

connect 4-7

Syntax 4-8

disconnect 4-8

Syntax 4-8

isConnected 4-8

Syntax 4-8

Nonblocking API C++ Code Examples 4-8

Login and Logout 4-8

Nonblocking API C Code Examples 4-14

Login and Logout 4-14

A P P E N D I X A List of Error Codes A-1

Introduction A-1

List of Error Codes A-1


OL-31824-01

About this Guide

Published: July 30, 2014

IntroductionThis document describes the Cisco Service Control Subscriber Manager C/C++ API.

You use the Cisco Service Control Subscriber Manager C/C++ API to update, query, and configure the Cisco Service Control Subscriber Manager. This API has two parts, which you can use separately or together without restriction:

• Cisco Service Control Subscriber Manager Nonblocking C/C++ API—A high-performance API with low visibility to errors and to operation results. This part of the API supports automatic integrations with OSS/AAA systems.

• Cisco Service Control Subscriber Manager Blocking C/C++ API— This part of the API supports user-interface applications, which access and manage the Cisco Service Control Subscriber Manager.

Note A set of APIs with the same functionality is also available for the Java environment.

This document is for networking or computer technicians responsible for configuring the Cisco Service Control Subscriber Manager. It is also intended for the operator who manages Cisco Service Control Engine (Cisco SCE) platforms.

Document Revision HistoryThe following Document Revision History table records the changes made to this document.

Table 1 Document Revision History

RevisionCisco Service Control Release and Date Change Summary

OL-31824-01 Release 5.0.x

July 30, 2014

First version of this document (new for the Release 5.0.x train).


OL-31824-01

OrganizationThis guide contains the following sections.

Related DocumentationUse this document in conjunction with all the Cisco Service Control Subscriber Manager user, API, and reference guides.

ConventionsThis document uses the following conventions.

Table 2 Document Organization

Section Title Description

Chapter 1 Getting Started Describes the platforms on which the C/C++ API can be used, and how to install, compile, and start running the C/C++ API component.

Chapter 2 General API Concepts Describes the various concepts that are used when working with the SM C/C++ API.

Chapter 3 Blocking API Describes the features and operation of the blocking API and provides code examples.

Chapter 4 Nonblocking API Describes the features and operation of the nonblocking API and provides code examples.

Appendix A List of Error Codes Lists the error codes that are used in the C/C++ API.

Table 3 Conventions

Convention Indication

bold font Commands and keywords and user-entered text appear in bold font.

italic font Document titles, new or emphasized terms, and arguments for which you supply values are in italic font.

[ ] Elements in square brackets are optional.

{x | y | z } Required alternative keywords are grouped in braces and separated by vertical bars.

[ x | y | z ] Optional alternative keywords are grouped in brackets and separated by vertical bars.

string Nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.

courier font Terminal sessions and information the system displays appear in courier font.

< > Nonprinting characters such as passwords are in angle brackets.


OL-31824-01

Note Means reader take note.

Tip Means the following information will help you solve a problem.

Caution Means reader be careful. In this situation, you might perform an action that could result in equipment damage or loss of data.

Timesaver Means the described action saves time. You can save time by performing the action described in the paragraph.

Warning Means reader be warned. In this situation, you might perform an action that could result in bodily injury.

Obtaining Documentation and Submitting a Service RequestFor information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gathering additional information, see What’s New in Cisco Product Documentation at: http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html.

Subscribe to What’s New in Cisco Product Documentation, which lists all new and revised Cisco technical documentation, as an RSS feed and deliver content directly to your desktop using a reader application. The RSS feeds are a free service.

[ ] Default responses to system prompts are in square brackets.

!, # An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line.

Table 3 Conventions (continued)


OL-31824-01

http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html


OL-31824-01

Cisco Service ControlOL-31824-01

C H A P T E R 1
Getting Started

IntroductionThis chapter describes the platforms on which you can use the Cisco Service Control Subscriber Manager C/C++ API. It also explains how to install, compile, and start running the Cisco Service Control Subscriber Manager C/C++ API.

This chapter consists of the following sections:

• Platforms and Compilers, page 1-1

• Installation Package Contents, page 1-1

• Installing the Cisco Service Control Subscriber Manager C/C++ API, page 1-2

• Compiling and Running the Cisco Service Control Subscriber Manager C/C++ API, page 1-3

Platforms and Compilers The Service Control Management Suite (SCMS) SM C/C++ API was developed and tested on Windows, Solaris, and Linux platforms. It was compiled on Windows by using the Microsoft Visual C++ 6 compiler, on Linux by using the GCC 3.2.3 compiler. On Solaris, the API is complied by using only the GCC 2.95 compiler.

Installation Package Contents For brevity, the installation directory, sm-c-api-vvv.bb, is referred to as <installdir>, where vvv and bb stand for the Cisco Service Control Subscriber Manager C/C++ API version and build number. Table 1-1 presents the layout of the installation directory.

The <installdir>/winnt folder contains the smapi.dll file, which is the Windows API executable. It also contains additional dynamic link library (DLL) and LIB files required to operate the Windows API.

The <installdir>/solaris folder contains the libsmapi.so file, which is the Solaris API executable.

The <installdir>/linux folder contains the libsmapi.so file, which is the Linux API executable.

The <installdir>/linux-64 folder contains the libsmapi.so file, which is the Linux API Executable for a 64-bit machine.

1-1 Subscriber Manager C/C++ API Programmer Guide

Chapter 1 Getting Started Installing the Cisco Service Control Subscriber Manager C/C++ API

The <installdir>/include folder contains the API C/C++ header files.

The <installdir>/include/system folder contains the C++ API internal header files.

Installing the Cisco Service Control Subscriber Manager C/C++ API

The Cisco Service Control Subscriber Manager C/C++ API distribution is part of the Cisco Service Control Subscriber Manager Login Event Generator (LEG) distribution file and is located in the sm_api directory. The Cisco Service Control Subscriber Manager C/C++ API is packaged in a UNIX tar file. You can extract the Cisco Service Control Subscriber Manager C/C++ API by using the UNIX tar utility or most Windows compression utilities.

• Installing the Cisco Service Control Subscriber Manager LEG on a UNIX Platform, page 1-3

• Installing the Cisco Service Control Subscriber Manager LEG on a Windows Platform, page 1-3

Table 1-1 Layout of Installation Directory

Folder Subfolder (as applicable) Filename

<installdir> — README.csmapi

— include BasicTypes.h

— — Common.h

— — GeneralDefs.h

— — Logger.h

— — PrintLogger.h

— — SmApiBlocking.h

— — SmApiBlocking_c.h

— — SmApiNonBlocking.h

— — SmApiNonBlocking_c.h

— include/system OperationHandleInterface.h

— — OperationResultInterface.h

— linux libsmapi.so

— solaris libsmapi.so

— winnt asn1ber.dll

— — asn1ber.lib

— — asn1rt.dll

— — asn1rt.lib

— — SmApi.dll

— — SmApi.lib

1-2Cisco Service Control Subscriber Manager C/C++ API Programmer Guide

OL-31824-01

Chapter 1 Getting Started Installing the Cisco Service Control Subscriber Manager LEG on a UNIX Platform

Installing the Cisco Service Control Subscriber Manager LEG on a UNIX Platform

Step 1 Extract the Cisco Service Control Subscriber Manager LEG distribution file.

Step 2 Locate the C/C++ SM API distribution file, sm-c-api-dist.tar.

Step 3 Extract the C/C++ API package tar file:

#> tar -xvf sm-c-api-dist.tar

Installing the Cisco Service Control Subscriber Manager LEG on a Windows Platform

Extract the Cisco Service Control Subscriber Manager LEG package by using a zip extractor (such as WinZip).

Compiling and Running the Cisco Service Control Subscriber Manager C/C++ API

The API connects to the Proprietary Remote Procedure Call (PRPC) server on the Cisco Service Control Subscriber Manager. For the API to work, the following conditions must be met:

• The Cisco Service Control Subscriber Manager must be operating, and reachable from the machine that hosts the API.

• The PRPC server on the Cisco Service Control Subscriber Manager must be started.

The PRPC server is a proprietary Remote Procedure Call (RPC) protocol designed by Cisco. For additional information, see the Cisco Service Control Management Suite Subscriber Manager User Guide.

• Compiling and Running a Program on Windows, page 1-3

• Compiling and Running a Program on Solaris, page 1-4

• Compiling and Running a Program on Linux, page 1-5

Note Compile the C/C++ API with a 32-bit compiler or 64-bit compiler.

Compiling and Running a Program on Windows

Step 1 Ensure that smapi.dll and the other DLL files are in your path or in the directory of your executable.

Step 2 Ensure that the include folder is in your include path of the compilation.


OL-31824-01

http://www.cisco.com/en/US/docs/cable/serv_exch/serv_control/broadband_app/rel40x/smug/smug.html


Chapter 1 Getting Started Compiling and Running a Program on Solaris

Example Using Microsoft Visual C++ 6.0

Step 1 Enter the project settings, click the C++ tab, and then choose the Preprocessor category.

Step 2 Add the include directory path in the Additional Include directories line.

Step 3 Ensure that the smapi.lib file is in your linkage path.

Step 4 Enter the project settings and click the Link tab. Add the smapi.lib file to the Object\Library modules line.

Step 5 Include the relevant API header file in your source code, and compile your code.

Compiling and Running a Program on Solaris

Step 1 Ensure that the libsmapi.so folder is in your LD_LIBRARY_PATH.

For example, when using the Bash shell type, use the following command line:

bash-2.03$ export set LD_LIBRARY_PATH=$LDLIBRARY_PATH:the-libsmapi.so-folder


For example, when using GCC, add the include folder after the -I option, as follows:

>gcc -c -o TestSmApi.o -Ism-api-header-file-folder-Ism-api-header-file-folder/system/ TestSmApi.cpp

Step 3 Ensure that the libsmapi.so file is in your linkage line or load it dynamically.

Link your object file to the pthread and socket library, as follows:

>gcc -o testSmApi TestSmApi.o -lsmapi -lpthread -lsocket


OL-31824-01

Chapter 1 Getting Started Compiling and Running a Program on Linux

Compiling and Running a Program on Linux

Step 1 Ensure that the libsmapi.so folder is in your LD_LIBRARY_PATH.

For example, when using the Bash shell type, use the following command line:

bash-2.03$ export set LD_LIBRARY_PATH=$LDLIBRARY_PATH:the-libsmapi.so-folder

Step 2 Enter your password if prompted.


For example, when using GCC, add the include folder after the -I option, as follows:

>gcc -c -o TestSmApi.o -Ism-api-header-file-folder-Ism-api-header-file-folder/system/ TestSmApi.cpp

Step 4 Ensure that the libsmapi.so file is in your linkage line or load it dynamically.

Specify the location of libsmapi.so using the -L option. Link your object file to the pthread and stdc++ libraries, as follows:

>gcc -o testSmApi TestSmApi.o -lsmapi -lpthread -lstdc++ -L<lib path>


OL-31824-01

Chapter 1 Getting Started Compiling and Running a Program on Linux


OL-31824-01


C H A P T E R 2
General API Concepts

IntroductionThis chapter describes the various concepts that are used when working with the Cisco Service Control Subscriber Manager C/C++ API.

• Blocking API and Nonblocking API, page 2-1

• Reliability, page 2-2

• C API Versus C++ API, page 2-2

• API Initialization, page 2-4

• API Finalization, page 2-5

• ReturnCode Structure, page 2-6

• ErrorCode Structure, page 2-7

• Subscriber Name Format, page 2-7

• Network ID Mappings, page 2-7

• Subscriber Domains, page 2-9

• Subscriber Properties, page 2-10

• Custom Properties, page 2-10

• Logging Capabilities, page 2-10

• Disconnect Callback Listener, page 2-11

• Signal Handling, page 2-11

• Practical Tips, page 2-12

Blocking API and Nonblocking APIThis section describes the differences between the Blocking API and Nonblocking API operations.

• Blocking API, page 2-2

• Nonblocking API, page 2-2


Chapter 2 General API Concepts Blocking API

Blocking APIFor a Blocking API operation, which is the common type, every method returns after its operation is performed.

The Cisco Service Control Subscriber Manager Blocking C/C++ API provides a wide range of operations and is a superset of the Nonblocking API functionality.

Nonblocking APIFor a Nonblocking API operation, every method returns immediately, even before the operation completes. The operation results are returned either to a set of user-defined callbacks or not returned at all.

The Nonblocking method is advantageous when the operation is lengthy and involves I/O. Operation is performed in a separate thread and this allows the calling program to continue doing other tasks, which improves overall system performance.

The Cisco Service Control Subscriber Manager Nonblocking C/C++ API contains a small number of nonblocking operations. The API supports retrieval of operation results by using result callbacks.

ReliabilityThe Service Control Management Suite (SCMS) SM C/C++ API is reliable in the sense that the operations performed on the API are kept until the Cisco Service Control Subscriber Manager returns their associated results. If the connection to the Cisco Service Control Subscriber Manager is lost, operations that were not sent to the Cisco Service Control Subscriber Manager and operations whose results did not yet return from the Cisco Service Control Subscriber Manager are sent to the Cisco Service Control Subscriber Manager immediately on reconnection. The order of operation invocation is maintained at all times.

C API Versus C++ APIThe C and C++ APIs are essentially the same. The C API is actually a thin wrapper over the C++ API, with method prototype and signature changes imposed by the constraint of C not being an object-oriented programming language.

The following sections describe the differences between the C and C++ APIs and provide some examples:

• Method Names, page 2-3

• Handle Pointers, page 2-3


OL-31824-01

Chapter 2 General API Concepts Method Names

Method NamesThe method names of the C API are the same as those of the C++ API, except that the C API method names have an identifying prefix:

• The Blocking C API method names are prefixed with SMB_.

• The Nonblocking C API methods names are prefixed with SMNB_.

Note The descriptions of methods in this document use the name and signature of the C++ API methods.

For example, both the Blocking and Nonblocking C++ APIs provide a login method. The method in the Blocking C API is called SMB_login and the method in the Nonblocking C API is called SMNB_login.

Handle PointersThe Blocking and Nonblocking APIs are C++ objects. Several API instances can co-exist in a single process; each has its own socket and state. The handle concept is introduced to provide the same functionality in the C API. Each C API method accepts a handle as its first argument. The handle identifies the C API instance on which the caller wants to operate. Calling the SMB_init or SMNB_init method creates a new C API instance; the return value of these methods provides the handle to the instance. For more information, see the “API Initialization” section on page 2-4.

Blocking API—Example

The C++ Blocking API logoutByName method signature

ReturnCode* logoutByName(char* argName, char** argMappings, MappingType* argMappingTypes, int argMappingsSize)

is translated into C Blocking API as follows:

ReturnCode* SMB_logoutByName(SMB_HANDLE argApiHandle, char* argName, char** argMappings, MappingType* argMappingTypes, int argMappingsSize);

Nonblocking API—Example

The C++ Nonblocking API logoutByName method signature

int logoutByName(char* argName, char** argMappings, MappingType* argMappingTypes, int argMappingsSize);

is translated into C Nonblocking API as follows:

int SMNB_logoutByName(SMNB_HANDLE argApiHandle, char* argName, char** argMappings, MappingType* argMappingTypes, int argMappingsSize);


OL-31824-01

Chapter 2 General API Concepts API Initialization

API InitializationThere are three main steps in initializing the API:

Step 1 Construct the API using one of its two constructors. See the Constructing the API, page 2-4.

Step 2 Perform API-specific setup operations. See the Performing Setup Operations, page 2-5.

Step 3 Connect the API to the Cisco Service Control Subscriber Manager. See the Connecting to the Cisco Service Control Subscriber Manager, page 2-5.

You can find the initialization examples in the code examples section under each API.

Constructing the APIBoth C and C++ Blocking and Nonblocking APIs must construct and initialize the API. Check whether the initialization succeeded before you proceed.

To construct and initialize the C++ API, construct an API object and call the init function as shown in the following example:

SmApiNonBlocking nbapi;if (!nbapi.init(0,2000000,10,30)){ exit(1);}

To construct and initialize the C API, call the init function, which allocates and initializes the API. For example:

SMNB_HANDLE nbapi = SMNB_init(0,2000000,10,30);if (nbapi == NULL){ exit(1);}

Setting the LEG Name

Set the Login Event Generator (LEG) name if you intend to turn on the Cisco Service Control Subscriber Manager LEG failure processing options in the Cisco Service Control Subscriber Manager. For more information about LEGs and Cisco Service Control Subscriber Manager-LEG failure handling, see Cisco Service Control Management Suite Subscriber Manager User Guide.

To set the LEG name, call the relevant setName function in the API. The Cisco Service Control Subscriber Manager uses the LEG name when recovering from a connection failure. A constant string that identifies the API is appended to the LEG name as follows:

• For Blocking API—.B.SM-API.C

• For Nonblocking API—.NB.SM-API.C

Setting the LEG Name Example (Blocking API)

If the provided LEG name is my-leg.10.1.12.45-version-1.0, the actual LEG name is my-leg.10.1.12.45-version-1.0.B.SM-API.C.

If no name is set, the LEG uses the hostname of the machine as the prefix of the name.


OL-31824-01


Chapter 2 General API Concepts Performing Setup Operations

For additional information about Cisco Service Control Subscriber Manager-LEG failure handling, see the “Configuration File Options” appendix of Cisco Service Control Management Suite Subscriber Manager User Guide.

Performing Setup OperationsThe setup operations for the two APIs differ. Both APIs support setting a disconnect listener, which is described in the “Disconnect Callback Listener” section on page 2-11.

The following sections describe the setup operations for the Blocking API and the Nonblocking API:

• Blocking API Setup, page 2-5

• Nonblocking API Setup, page 2-5

Blocking API Setup

To set up the Blocking API, you must set an operation timeout value. For more information, see the Chapter 3, “Blocking API”.

Nonblocking API Setup

To set up the Nonblocking API, you must set a disconnect callback. For more information, see the Chapter 4, “Nonblocking API”.

Connecting to the Cisco Service Control Subscriber ManagerTo connect to the Cisco Service Control Subscriber Manager, use one of the following connect methods:

• The following example shows how to connect when using the C++ APIs:

connect(char* host, Uint16 argPort = 14374)

• The following example shows how to connect when using the C Blocking API:

SMB_connect(SMB_HANDLE argApiHandle, char* host, Uint16 argPort)

• The following example shows how to connect when using the C Nonblocking API:

SMNB_connect(SMNB_HANDLE argApiHandle, char* host, Uint16 argPort)

The argHostName parameter can be either an IP address or a reachable hostname. At any time during the API operation, you can check if the API is connected by using one of the variants of the isConnected function.

API FinalizationBoth C and C++ Blocking and Nonblocking APIs must disconnect from the Cisco Service Control Subscriber Manager and free the memory of the API:

• For the C++ APIs, call the disconnect method and free the API object.

• For the C APIs, call the appropriate disconnect function and then free the API by using the appropriate release function.


OL-31824-01



Chapter 2 General API Concepts ReturnCode Structure

ReturnCode StructureThe results of the API operations are returned using a generic structure called ReturnCode. The ReturnCode structure contains several parameters:

• u—Union of all variables and pointers to variables that are the actual returned values.

• type—Return code type parameter (ReturnCodeType enumeration) that defines the type of the value (u) that the ReturnCode structure holds.

• size—Number of elements in the value. If size is equal to 1, there is one element in the value, such as a scalar, character string, void, or error. If size is greater than 1, there are several elements in the array, and the type should be one of the array types.

The API allocates the return code structure and the API user must free the structure. You can use the freeReturnCode utility function to safely free the structure.

Additional return code structure utility functions are:

• printReturnCode—Prints the ReturnCode structure value to the stdout.

• isReturnCodeError—Checks whether the ReturnCode structure is an error.

DefinitionThis is an example definition from the GeneralDefs.h header file:

OSAL_DllExport typedef struct ReturnCode_t{ ReturnCodeType type; int size; /* number of elements in the union element */ /* (for example: stringVal will have size=1) */ union {/* use union value according to the type value */ bool boolVal; short shortVal; int intVal; long longVal; char* stringVal; bool* boolArrayVal; short* shortArrayVal; int* intArrayVal; long* longArrayVal; char** stringArrayVal; ErrorCode* errorCode; struct ReturnCode_t** objectArray; } u;}ReturnCode;

Return Code Structure ExampleIn the following example, the API retrieves and displays the subscriber data of subscriber1. The returned structure contains an array of ReturnCode structures held by the objectArray union value. Each structure contains a different value type. For additional information, see the “getSubscriber” section on page 3-22. This example uses the isReturnCodeError and freeReturnCode methods.

ReturnCode* subFields = bapi.getSubscriber("subscriber1");if (isReturnCodeError(subFields) == false){ printf("\tname:\t\t%s\n", subFields->u.objectArray[0]->u.stringVal);


OL-31824-01

Chapter 2 General API Concepts ErrorCode Structure

printf("\tmapping:\t%s\n", subFields->u.objectArray[1]->u.stringArrayVal[0]); printf("\tdomain:\t\t%s\n", subFields->u.objectArray[3]->u.stringVal); printf("\tautologout:\t%d\n", subFields->u.objectArray[8]->u.intVal);}else{ printf("error in subscriber retrieval\n");}freeReturnCode(subFields);

ErrorCode StructureThe ErrorCode structure can be one of the values of the return code structure. This structure describes the error that occurred. The structure consists of the following parameters:

• type—ErrorCodeType enumeration that describes the error. See the GeneralDefs.h file for additional information.

• message—Specific error code.

• name—Currently not used.

DefinitionThis is an example definition from the GeneralDefs.h header file:

OSAL_DllExport typedef struct ErrorCode_t{ ErrorCodeType type; /* type of the error see enumeration */ char* name; /* currently not used */ char* message; /* error message */}ErrorCode;

Subscriber Name FormatMost methods of the Blocking and Nonblocking APIs require the subscriber name as an input parameter. This section lists the formatting rules of a subscriber name.

• A subscriber name can contain up to 64 characters.

• A subscriber name can be made up of all printable characters with an ASCII code between 32 and 126 (inclusive), except for 34 ("), 39 ('), and 96 (`).

• If the subscriber name begins with a non-alphanumeric character, it must be preceded by a backslash (\).

Network ID MappingsA network ID mapping is a network identifier that the SCE device can map to a specific subscriber record. A typical example of a network ID mapping (or simply, mapping) is an IP address. For additional information, see the Cisco Service Control Management Suite Subscriber Manager User Guide. Currently, the Cisco Service Control Solution supports IP address, IP range, private IP address over VPN, private IP range over VPN, and VLAN mappings.


OL-31824-01


Chapter 2 General API Concepts Specifying IP Address Mapping

Both Blocking and Nonblocking APIs contain operations that accept mappings as a parameter. Examples are:

• The addSubscriber operation (Blocking APIs)

• The login operation (Blocking or Nonblocking APIs)

When passing mappings to an API method, the caller is requested to provide two parameters:

• A character string (char*) mapping identifiers or array of character strings (char**) mappings.

• A MappingType enumeration or array of MappingType variables.

When passing arrays, the MappingType variables array must contain the same number of elements as the mappings array.

The API supports the following subscriber mapping types (defined by the MappingType enumeration):

• IP addresses or IP ranges

• (From Cisco Service Control Subscriber Manager Release 3.8.5) IPv6 address

• Private IP addresses or private IP ranges over VPN

• VLAN tags

Specifying IP Address MappingThe string format of an IP address is the commonly used decimal notation:

IP-Address=[0-255].[0-255].[0-255].[0-255]

Example:

216.109.118.66

The GeneralDefs.h header file provides the mapping type of an IP address:

• IP_RANGE specifies IP mapping (IP-Address or IP-Range that matches the mapping identifier with the same index in the mapping identifier array).

Specifying IP Range MappingThe 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:

• 10.1.1.10/32 is an IP range with a complete mask, that is, a regular IP address.

• 10.1.1.0/24 is an IP range with a 24-bit mask, that is, all the addresses ranging between 10.1.1.0 and 10.1.1.255.

Note The mapping type of an IP range is identical to the mapping type of the IP address.


OL-31824-01

Chapter 2 General API Concepts Specifying Private IP Address or Private IP Range over VPN Mapping

Specifying Private IP Address or Private IP Range over VPN MappingThe string format of an IP address and an IP range are described in the “Specifying IP Address Mapping” section on page 2-8 and the “Specifying IP Range Mapping” section on page 2-8, respectively. When the network ID mapping uses an IP address or range over VPN, the string format includes the VPN name.

Examples:

• 10.1.1.10@VPN1 is an IP address over the VPN named VPN1.

• 10.1.1.0/24@VPN2 is an IP range with a 24-bit mask, that is, all the addresses ranging between 10.1.1.0 and 10.1.1.255 over the VPN named VPN2.

Note The mapping type of an IP address or IP range over VPN is identical to the mapping type of the IP address.

Specifying VLAN Tag MappingThe string format for VLAN tag mapping is VLAN-tag = 0-4095. The string is a decimal in the specified range.

The GeneralDefs.h header file provides the mapping type of a VPN, which is used to specify VLAN-tags as network IDs.

Note The mapping type, VLAN, is deprecated. Use the VPN mapping type instead.

Specifying IPv6 Address MappingThe string format for an IPv6 address mapping is a hexadecimal string that follows the RFC 2373 standard.

Example:

2005:1:2:23::/64

The GeneralDefs.h header file provides the mapping type of an IPv6 address:

• TYPE_IPV6 specifies IPv6 mapping.

Subscriber DomainsThe Cisco Service Control Management Suite Subscriber Manager User Guide describes the domain concept in detail. A domain is an identifier that tells the Cisco Service Control Subscriber Manager which Cisco SCE devices to update with the subscriber record.

A domain name is of type (char*). During system installation, the network administrator determines the system domain names, which vary from installation to installation. The APIs include methods that specify the domain to which a subscriber belongs and allow queries about the domain names of the


OL-31824-01


Chapter 2 General API Concepts Subscriber Properties

system. If an API operation specifies a domain name that does not exist in the Cisco Service Control Subscriber Manager domain repository, it is considered an error and an ERROR_CODE_DOMAIN_NOT_FOUND error ReturnCode is returned.

The Cisco Service Control Subscriber Manager automatic domain roaming feature enables you to move subscribers among domains by calling the login method for a subscriber with an updated domain parameter. For additional information, see the “login” section on page 3-4.

Note Automatic domain roaming is not backward compatible with previous versions of the Cisco Service Control Subscriber Manager API, which did not allow changing the domain of the subscriber.

Subscriber PropertiesSeveral operations manipulate subscriber properties. A subscriber property is a key-value pair that affects the way the SCE analyzes and reacts to network traffic generated by the subscriber.

For more information about properties, see the Cisco Service Control Management Suite Subscriber Manager User Guide and the Cisco Service Control Application for Broadband User Guide. The SCA BB user guide provides application-specific information. It lists the subscriber properties that exist in the application running on your system, the allowed value set, and the significance of each property value.

To format subscriber properties for C/C++ API operations, use the string arrays (char**) propertyKeys and propertyValues.

Note The arrays must be of the same length, and NULL entries are forbidden. Each key in the keys array has a matching entry in the values array. The value for propertyKeys[j] resides in propertyValues[j].

Example:

If the property keys array is {"packageId","monitor"} and the property values array is {"5","1"}, the properties are packageId=5, monitor=1.

Custom PropertiesSome operations manipulate custom properties. Custom properties are similar to subscriber properties, but do not affect how the SCE analyzes and manipulates the subscriber traffic. The application management modules use custom properties to store additional information for each subscriber.

To format custom properties, use the string (char**) arrays customPropertyKeys and customPropertyValues, in the same manner as in the “Subscriber Properties” section on page 2-10.

Logging CapabilitiesThe API package contains a Logger abstract class that can be inherited and used to integrate the Cisco Service Control Subscriber Manager API with the host application log. The Logger class exposes four basic levels of logging—error messages, warning messages, informative messages, and several levels of trace messages. Both the Blocking and Nonblocking API have this capability. The Logger.h header file provides the Logger class.


OL-31824-01



http://www.cisco.com/en/US/docs/cable/serv_exch/serv_control/broadband_app/rel40x/scabbug/scabbug.html

Chapter 2 General API Concepts Disconnect Callback Listener

As you use the API, you should implement a logger by inheriting from the Logger class. To enable the API to use this logger, the code should call the setLogger method of the C++ implementation of the API.

To test and implement a LEG, the API package provides the PrintLogger class, which is a basic implementation of the Logger class that prints the log messages to the standard error (STDERR). With the API, you can initiate the PrintLogger object, set its logging level by using the setLoggingLevels method of the PrintLogger class, and pass the logger object to the API by using the API setLogger method. The PrintLogger.h header file provides the PrintLogger class.

Disconnect Callback ListenerBoth Blocking and Nonblocking APIs enable you to set a disconnect callback listener to be notified when the API is disconnected from the Cisco Service Control Subscriber Manager. Define the disconnect callback as follows:

typedef void (*ConnectionIsDownCallBackFunc)();

To set the disconnect listener, use the setDisconnectListener method.

Disconnect Callback Listener ExampleThe following example is a basic implementation of a disconnect callback listener that prints a message to stdout and exits:

#include "GeneralDefs.h"void connectionIsDown(){ printf("Message: connection is down."); exit(0);}

Signal HandlingThe Cisco Service Control Subscriber Manager C/C++ API as a networking module might handle sockets that are closed by the Cisco Service Control Subscriber Manager, for example, if the Cisco Service Control Subscriber Manager is restarted, which might cause“Broken Pipe” signals. It is especially advisable for the UNIX environment to handle this signal.

To ignore the signal, add the following call:

sigignore(SIGPIPE);


OL-31824-01

Chapter 2 General API Concepts Practical Tips

Practical TipsWhen implementing the code that integrates the API with your application, consider the following practical tips:

• Connect to the Cisco Service Control Subscriber Manager once and maintain an open API connection to the Cisco Service Control Subscriber Manager at all times, using the API many times. Establishing a connection is a timely procedure, which allocates resources on the Cisco Service Control Subscriber Manager side and the API client side.

• Share the API connection between your threads. It is best to have one connection per LEG. Multiple connections require more resources on the Cisco Service Control Subscriber Manager side and client side.

• Do not implement synchronization of the calls to the API. The client automatically synchronizes calls to the API.

• Place the API clients (LEGs) in the same order of the Cisco Service Control Subscriber Manager machine processor number.

• If the LEG application has bursts of logon operations, enlarge the internal buffer size accordingly to hold these bursts (Nonblocking flavor).

• During the integration, set the Cisco Service Control Subscriber Manager logon_logging_enabled configuration parameter to view the API operations in the Cisco Service Control Subscriber Manager log to troubleshoot the integration, if any problems arise.

• Use the debug mode for the LEG application that logs (prints) the return values of the nonblocking operations.

• Use the automatic reconnect feature to improve the resiliency of the connection to the Cisco Service Control Subscriber Manager.

• In cluster setups, connect the API by using the virtual IP address of the cluster, not the management IP address of one of the machines.


OL-31824-01


C H A P T E R 3
Blocking API

IntroductionThis chapter describes the features and operations of the Blocking API and provides code examples. It also introduces reply timeout feature that is unique to the Blocking API.

Note If you only need to develop an automatic integration, skip this chapter and go directly to Chapter 4, “Nonblocking API.”

• Multithreading Support, page 3-1

• Operation Timeout Error Code, page 3-2

• Blocking API Methods, page 3-2

• Blocking API C++ Code Examples, page 3-42

• Blocking API C Code Examples, page 3-45

Multithreading SupportThe Blocking API supports a configurable number of threads calling its methods simultaneously. For more information about configuring the number of threads, see the “C++ init Method” section on page 3-36.

Note In a multithreaded scenario for the Blocking API, the order of invocation is not guaranteed.

Multithreading Support ExampleThread 0 calls operation 0 at time 0, and thread 1 calls operation 1 at time 1, where time 1 is later than time 0. In this example, it is possible that operation 1 may be performed before operation 0, as shown in Figure 3-1 (the vertical scale is time).


Chapter 3 Blocking API Operation Timeout Error Code

Figure 3-1 Multithreading Support

The Cisco Service Control Subscriber Manager allocates five threads to process each API instance. You should develop a multithreaded application that uses the API with a number of threads (in the order of the five threads). Implementing with more threads might result in longer delays for calling the threads.

Operation Timeout Error CodeA Blocking operation returns only when the operation result has been retrieved from the Cisco Service Control Subscriber Manager. If a networking malfunction or other error prevents the operation result from being retrieved, the caller waits indefinitely. The Cisco Service Control Subscriber Manager API provides ways to work around this situation.

The setReplyTimeout method of the reply timeout feature enables the caller to set a timeout. It returns a ReturnCode with the ERROR_CODE_CLIENT_OPERATION_TIMEOUT error when a reply does not return within the timeout period.

Calling the setReplyTimeout function with an int value sets a reply timeout. The reply timeout is interpreted in milliseconds. A zero value indicates that the operation should wait (freeze or stop responding) until a result arrives—or indefinitely, if no result arrives.

Blocking API MethodsThis section lists the methods of the Blocking API.

The Blocking API is a superset of the Nonblocking API. Except for differences in return values and result handling, identical operations in both APIs have the same functions and syntax structure.

The C API and C++ API share the same function signature as the first parameter in all functions, except for SMB_ prefix, for all function names for the Blocking C APIs and for the API handle of type SMB_HANDLE. The function description defines any other differences between the APIs.

The Blocking API subscriber management methods can be classified into the following categories:

1571

10

Thread 0 :

op-0 : operation

op-1 : operation

op-1 : result

op-0 : result

Thread 1 : SM Blocking API :


OL-31824-01

Chapter 3 Blocking API Blocking API Methods

• Dynamic IP and property allocation—For using the Cisco Service Control Subscriber Manager API for integration with an AAA system, the following methods are relevant:

– login, page 3-4

– logoutByName, page 3-8

– logoutByNameFromDomain, page 3-10

– logoutByMapping, page 3-12

– loginCable, page 3-13

– logoutCable, page 3-15

Note These methods are not designed to add or remove subscribers from the database, but to modify dynamic parameters (such as IP addresses) of existing subscribers.

• Static/manual subscriber configuration—For GUI usage, for example, the following methods are relevant:

– addSubscriber, page 3-16

– removeSubscriber, page 3-18

– removeAllSubscribers, page 3-19

– setPropertiesToDefault, page 3-33

– removeCustomProperties, page 3-34

• Simple read-only operations performed independently in subscriber awareness mode—The following methods are relevant:

– getNumberOfSubscribers, page 3-20

– getNumberOfSubscribersInDomain, page 3-21

– getSubscriber, page 3-22

– subscriberExists, page 3-23

– subscriberLoggedIn, page 3-24

– getSubscriberNameByMapping, page 3-25

– getSubscriberNames (all), page 3-26

– getSubscriberNames (filter by property), page 3-28

– getSubscriberNamesInDomain, page 3-29

– getSubscriberNamesWithPrefix, page 3-31

– getSubscriberNamesWithSuffix, page 3-32

– getDomains, page 3-33

It is possible to combine methods from different categories in a single application. The classification is presented only for clarification purposes.

• API maintenance—Initialization, connection, disconnection—The following methods are relevant:

– C++ setLogger Method, page 3-35

– C++ init Method, page 3-36

– C SMB_init Function, page 3-37


OL-31824-01

Chapter 3 Blocking API login

– C SMB_release Function, page 3-38

– setReconnectTimeout, page 3-38

– setName, page 3-39

– connect, page 3-40

– disconnect, page 3-40

– isConnected, page 3-41

Note The examples that appear at the end of the described methods are in C++. Every example described at the end of the methods should be preceded by the following sample code:SmApiBlocking bapi;

// Init with default parameters

bapi.init();

// Connect to the SM

bapi.connect((char*)"1.1.1.1");

loginThe following sections describe login operation information:

• Syntax, page 3-4

• Description, page 3-4

• Parameters, page 3-5

• Return Value, page 3-5

• Error Codes, page 3-5

• Example, page 3-6

Syntax

The login syntax is as follows:

ReturnCode* login(char* argName, char** argMappings, MappingType* argMappingTypes, int argMappingsSize, char** argPropertyKeys, char** argPropertyValues, int argPropertySize, char* argDomain, bool argIsAdditive, int argAutoLogoutTime)

Description

The login method adds or modifies a domain, mappings, and properties of a subscriber that already exists in the Cisco Service Control Subscriber Manager database. A login can be called with partial data, for example, with only mappings or only properties provided and NULL put in the unchanged fields.


OL-31824-01


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

If the subscriber does not exist in the Cisco Service Control Subscriber Manager database, it is created with the data provided.

Parameters

Login parameters are as follows:

• argName—For a description, see the “Subscriber Name Format” section on page 2-7.

• argMappings—For a description, see the “Network ID Mappings” section on page 2-7. If no mappings are specified, and the argIsAdditive parameter is TRUE, the previous mappings are retained. If no such mappings exist, the operation fails.

• argMappingTypes—For a description, see the “Network ID Mappings” section on page 2-7.

• argMappingsSize—The size of the argMappings and argMappingTypes arrays.

• argPropertyKeys—For a description, see the “Subscriber Properties” section on page 2-10.

• argPropertyValues—For description, see the “Subscriber Properties” section on page 2-10.

• argPropertySize—The size of the argPropertyKeys and argPropertyValues arrays.

• argDomain—For description, see the “Subscriber Domains” section on page 2-9.

If domain is NULL, but the subscriber already has a domain, the existing domain is retained.

If the domain differs from the domain that was previously assigned to the subscriber, the subscriber is removed automatically from the SCEs of the previous domain and moved to the SCEs of the new domain.

• argIsAdditive—Mapping parameters.

– TRUE—Adds the mappings provided by this call to the subscriber record.

– FALSE—Overrides the mappings that already exist in the subscriber record with the mappings provided by this call.

• argAutoLogoutTime—Applies only to the mappings provided as arguments to the login method.

– Positive value (N)—Automatically logs out the mappings (similar to a logout method being called) after N seconds.

– 0 value—Maintains the current expiration time for the given mappings.

– Negative value—Disables any expiration time that might have been set for the mappings given.

Return Value

The return value is a pointer to a ReturnCode structure with a void type, unless an error has occurred.

Error Codes

The following list presents the error codes that the login method might return:

• ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME

• ERROR_CODE_BAD_SUBSCRIBER_MAPPING

• ERROR_CODE_DATABASE_EXCEPTION


OL-31824-01


• ERROR_CODE_UNKNOWN

Instances of the following value specifications can cause this error:

– NULL value for the domain parameter for the subscriber that does not exist or does not have a domain

– Invalid values for the propertyValues parameter

For a description of error codes, see Appendix A, “List of Error Codes”.

Example

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

MappingType map_type = IP_RANGE;char* ip_address = "192.168.12.5";

bapi.login( "alpha", // subscriber name &ip_address, &map_type, 1, // one mapping NULL, NULL, 0, // no properties "subscribers", // domain true, // isMappingAdditive is true -1); // autoLogoutTime set to infinite

To add the IP address 192.168.12.5 overriding previous mappings:


bapi.login( "alpha", // subscriber name &ip_address, &map_type, 1, NULL, NULL,0, "subscribers", // domain false, // isMappingAdditive is false -1); // autoLogoutTime set to infinite

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


bapi.login( "alpha", // subscriber name &ip_address, &map_type, 1, NULL, NULL, 0, "subscribers", // domain false, // isMappingAdditive is false 300); // autoLogoutTime set to 300 seconds

To modify a dynamic property of alpha,for example, package ID:

char* prop_name = "packageID";char* prop_value = "10";

bapi.login(


OL-31824-01


"alpha", NULL, NULL, 0, &prop_name, // property key &prop_value, // property value 1, // one property "subscribers", // domain false, -1);

To add the IP address 192.168.12.5 to an existing subscriber named alpha without affecting existing mappings and to modify a dynamic property of alpha,for example, package ID:


char* prop_name = "packageID";char* prop_value = "10";

bapi.login( "alpha", &ip_address, &map_type, 1, &prop_name, // property key &prop_value, // property value 1, "subscribers", // domain true, // isMappingAdditive is set to true -1);

To add the IPv6 address abcc:abcd:bcde:fce1:10::/64 to an existing subscriber named alpha without affecting the existing mappings:

MappingType map_type = TYPE_IPV6;char* ip_address = "abcc:abcd:bcde:fce1:10::/64";bapi.login( "alpha", // subscriber name &ip_address, &map_type, 1, // one mapping NULL, NULL, 0, // no properties "subscribers", // domain true, // isMappingAdditive is true -1); // autoLogoutTime set to infinite

To add the IPv6 address abcd:bcde:fce1:10::/64 overriding the existing mappings:

MappingType map_type = TYPE_IPV6;char* ip_address = "abcd:bcde:fce1:10::/64";bapi.login( "alpha", // subscriber name &ip_address, &map_type, 1, NULL, NULL,0, "subscribers", // domain false, // isMappingAdditive is false -1); // autoLogoutTime set to infinite

To extend the auto logout time of the IPv6 address abcd:bcde:fce1:10::/64 that was previously assigned to alpha:

MappingType map_type = TYPE_IPV6;char* ip_address = "abcd:bcde:fce1:10::/64";


OL-31824-01

Chapter 3 Blocking API logoutByName

bapi.login( "alpha", // subscriber name &ip_address, &map_type, 1, NULL, NULL, 0, "subscribers", // domain false, // isMappingAdditive is false 300); // autoLogoutTime set to 300 seconds

To modify a dynamic property of alpha,for example, package ID:

char* prop_name = "packageID";char* prop_value = "10";bapi.login( "alpha", NULL, NULL, 0, &prop_name, // property key &prop_value, // property value 1, // one property "subscribers", // domain false, -1);

To add the IPv6 address abcd:bcde:fce1:10::/64 to an existing subscriber named alpha without affecting existing mappings and to modify a dynamic property of alpha, for example, package ID:

MappingType map_type = TYPE_IPV6;char* ip_address = "abcd:bcde:fce1:10::/64";char* prop_name = "packageID";char* prop_value = "10";bapi.login( "alpha", &ip_address, &map_type, 1, &prop_name, // property key &prop_value, // property value 1, "subscribers", // domain true, // isMappingAdditive is set to true -1);

logoutByNameThe following sections provide information about the logoutByName operation:







Syntax

The logoutByName syntax is as follows:

ReturnCode* logoutByName(char* argName,


OL-31824-01

Chapter 3 Blocking API logoutByName

char** argMappings, MappingType* argMappingTypes, int argMappingsSize)

Description

The logoutByName method locates the subscriber in the database and removes mappings from the subscriber.

Parameters

The logoutByName parameters are as follows:

argName—For description, see the “Subscriber Name Format” section on page 2-7.

argMappings—For description, see the “Network ID Mappings” section on page 2-7. If no mappings are specified, all the subscriber mappings are removed.

argMappingTypes—For description, see the “Network ID Mappings” section on page 2-7.

argMappingsSize—The size of the argMappings and argMappingTypes arrays.

Return Value

The return value is a pointer to a ReturnCode structure with a Boolean type:

• TRUE—If the subscriber was found and the subscriber mappings were removed from the subscriber database.

• FALSE—If the subscriber was not found in the subscriber database.

Error Codes

The following list provides the error codes that the logoutByName method might return:

• ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST

• ERROR_CODE _BAD_SUBSCRIBER_MAPPING



Example

To remove IP address 192.168.12.5 from subscriber alpha:


bapi.logoutByName( "alpha", &ip_address, &map_type, 1);

To remove the IPv6 address abcd:bcde:fce1:10::/64 from the subscriber alpha:

MappingType map_type = TYPE_IPV6;char* ip_address = "abcd:bcde:fce1:10::/64";


OL-31824-01

Chapter 3 Blocking API logoutByNameFromDomain

bapi.logoutByName( "alpha", &ip_address, &map_type, 1);

To remove all the IPv6 addresses from the subscriber alpha:

bapi.logoutByName("alpha", NULL, NULL,0);

To remove all the IP addresses from the subscriber alpha:

bapi.logoutByName("alpha", NULL, NULL,0);

logoutByNameFromDomainThe following sections provide information about the logoutByNameFromDomain operation:







Syntax

The logoutByNameFromDomain syntax is as follows:

ReturnCode* logoutByNameFromDomain (char* argName, char** argMappings, MappingType* argMappingTypes, int argMappingsSize, char* argDomain)

Description

The logoutByNameFromDomain method locates the subscriber in the database according to the specified domain and removes mappings from the subscriber.

Parameters

argName—For description, see the “Subscriber Name Format” section on page 2-7.

argMappings—For description, see the “Network ID Mappings” section on page 2-7. If no mappings are specified, all the subscriber mappings are removed.

argMappingTypes—For description, see the “Network ID Mappings” section on page 2-7.

argMappingsSize—The size of the argMappings and argMappingTypes arrays.

argDomain—See the description of subscriber domains in the “Subscriber Domains” section on page 2-9.

The operation fails if either of the following conditions exists:


OL-31824-01

Chapter 3 Blocking API logoutByNameFromDomain

• The domain is null, but the subscriber exists in the database and belongs to a domain.

• The domain specified is incorrect.

Return Value


• TRUE—If the subscriber was found and the subscriber mappings were removed from the subscriber database.


Error Codes

The following list provides error codes that logoutByNameFromDomain method might return:



• ERROR_CODE_SUBSCRIBER_DOMAIN_ASSOCIATION

• ERROR_CODE_DOMAIN_NOT_FOUND

• ERROR_CODE_NOT_A_SUBSCRIBER_DOMAIN



Example

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


bapi.logoutByNameFromDomain( "alpha", &ip_address, &map_type, 1, "subscribers");

To remove all IP addresses of subscriber alpha from domain subscribers:

bapi.logoutByNameFromDomain( "alpha", NULL, NULL, 0, "subscribers");

To remove the IPv6 address abcd:bcde:fce1:10::/64 of the subscriber alpha from the domain subscribers:

MappingType map_type = TYPE_IPV6;char* ip_address = "abcd:bcde:fce1:10::/64";bapi.logoutByNameFromDomain( "alpha", &ip_address, &map_type,


OL-31824-01

Chapter 3 Blocking API logoutByMapping

1, "subscribers");

To remove all the IPv6 addresses of the subscriber alpha from domain subscribers:

bapi.logoutByNameFromDomain( "alpha", NULL, NULL, 0, "subscribers");

logoutByMappingThe following sections provide information about the logoutByMapping operation:







Syntax

The logoutByMapping syntax is as follows:

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

Description

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

Parameters

argMapping—For description, see the “Network ID Mappings” section on page 2-7.

argMappingType—For description, see the “Network ID Mappings” section on page 2-7.

argDomain—For description, see the “Parameters” section on page 3-10 of the logoutByNameFromDomain method.

Return Value


• TRUE—If the subscriber was found and removed from the subscriber database.



OL-31824-01

Chapter 3 Blocking API loginCable

Error Codes

The following list provides error codes that logoutByMapping method might return:



• ERROR_CODE_SUBSCRIBER_DOMAIN_ASSOCIATION





Example

To remove the IP address 192.168.12.5 from domain subscribers:

bapi.logoutByMapping( "192.168.12.5", IP_RANGE, "subscribers");

To remove the IPv6 address abcd:bcde:fce1:10::/64 from the domain subscribers:

bapi.logoutByMapping( "abcd:bcde:fce1:10::/64", TYPE_IPV6, "subscribers");

loginCableThe following sections provide information about the loginCable operation:







Syntax

The loginCable syntax is as follows:

ReturnCode* loginCable(char* argCpe, char* argCm, char* argIp, int argLease, char* argDomain, char** argPropertyKeys, char** argPropertyValues, int argPropertySize)


OL-31824-01

Chapter 3 Blocking API loginCable

Description

The loginCable is a login method adapted for the cable environment, which calls the cable support module in the Cisco Service Control Subscriber Manager. This method logs in customer premise equipments (CPE) to the Cisco Service Control Subscriber Manager. To log in a cable modem, specify the cable modem MAC address in both CPE and cable modem arguments. For additional information, see the “CPE as Subscriber in Cable Environment” appendix of Cisco Service Control Management Suite Subscriber Manager User Guide.

Note The name of the CPE in the Cisco Service Control Subscriber Manager database is the concatenation of the CPE and cable modem values with two underscore (“_”) characters between them. The caller must ensure that the lengths of CPE and cable modem add up to no more than 38 characters.

Parameters

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

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

argIp—CPE IP address.

argLease—CPE lease time.

argDomain—For description, see the “Subscriber Domains” section on page 2-9.

The domain is usually CMTS IP.

Note Domain aliases must be set on the Cisco Service Control Subscriber Manager to correctly interpret the CMTS IP as a domain name. For information about alias configuration, see the “Default Domains Configuration” section of the Cisco SCMS Subscriber Manager User Guide.

argPropertyKeys—For description, see the “Subscriber Properties” section on page 2-10. If the CPE is provided with partial or no application properties, the values for the missing application properties are copied from the application properties of the cable modem to which this CPE belongs. Each cable modem application property thus serves as a default for the CPE under it.

argPropertyValues—For description, see the “Subscriber Properties” section on page 2-10.

argPropertySize—Size of the argPropertyKeys and argPropertyValues arrays.

Return Value

The return value is a pointer to a ReturnCode structure with a void type.

Error Codes

None.

Example

To add the IP address 192.168.12.5 to a cable modem called CM1 with two hours lease time:

bapi.loginCable(


OL-31824-01

http://www.cisco.com/en/US/docs/cable/serv_exch/serv_control/broadband_app/rel40x/smug/CPE_as_Subscriber_in_Cable_Environment.html



http://www.cisco.com/en/US/docs/cable/serv_exch/serv_control/broadband_app/rel40x/smug/Configuration_File_Options.html#wp1046175

http://www.cisco.com/en/US/docs/cable/serv_exch/serv_control/broadband_app/rel40x/smug/Configuration_File_Options.html#wp1046175


Chapter 3 Blocking API logoutCable

"CM1", "CM1", "192.168.12.5", 7200, // lease time in seconds "subscribers", NULL, NULL, 0); // no properties

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

bapi.loginCable( "CPE1", "CM1", "192.168.12.50", 3600, // lease time in seconds "subscribers", NULL, NULL, 0);

logoutCableThe following sections provide information about the logoutCable operation:







Syntax

The logoutCable syntax is as follows:

ReturnCode* logoutCable(char* argCpe, char* argCm, char* argIp, char* argDomain)

Description

The logoutCable method indicates a logout (CPE becoming offline) event to the Cisco Service Control Subscriber Manager cable support module.

Parameters

argCpe—See the description in the “Parameters” section on page 3-14 of the loginCable method.

argCm—See the description in the “Parameters” section on page 3-14 of the loginCable method.

argIp—See the description in the “Parameters” section on page 3-14 of the loginCable method.

argDomain—See the description in the “Parameters” section on page 3-14 of the loginCable method.


OL-31824-01

Chapter 3 Blocking API addSubscriber

Return Value


• TRUE—If the CPE was found and removed from the subscriber database.

• FALSE—If the CPE was not found in the subscriber database.

Error Codes

None.

Example

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

bool isExist = bapi.logoutCable( "CPE1", "CM1", "192.168.12.5", "subscribers");

addSubscriberThe following sections provide information about the addSubscriber operation:







Syntax

The addSubscriber syntax is as follows:

ReturnCode* addSubscriber(char* argName, char** argMappings, MappingType* argMappingTypes, int argMappingsSize, char** argPropertyKeys, char** argPropertyValues, int argPropertySize, char** argCustomPropertyKeys, char** argCustomPropertyValues, int argCustomPropertySize, char* argDomain)


OL-31824-01

Chapter 3 Blocking API addSubscriber

Description

The addSubscriber creates a new subscriber record according to the given data and adds it to the Cisco Service Control Subscriber Manager database. If a subscriber by this name already exists, it is removed before the new one is added. In contrast to the login method, which modifies fields passed to it and leaves unspecified fields unchanged, addSubscriber sets the subscriber exactly as specified by the parameters passed to it.

Note Use the login method for logging in existing subscribers, instead of using the addSubscriber method. Use login to set dynamic mappings and properties. Use addSubscriber method to set the static mappings and properties the first time the subscriber is created.

Note With addSubscriber method, the auto-logout feature is always disabled. To enable auto-logout, use the login method.

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 is left with no mappings.

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

Parameters

argName—See the description in the “Subscriber Name Format” section on page 2-7.

argMappings—See the description in the “Network ID Mappings” section on page 2-7.

argMappingTypes—See the description in the “Network ID Mappings” section on page 2-7.

argMappingsSize—Size of the argMappings and argMappingTypes arrays.

argPropertyKeys—See the description in the “Subscriber Properties” section on page 2-10.

argPropertyValues—See the description in the “Subscriber Properties” section on page 2-10.

argPropertySize—Size of the argPropertyKeys and argPropertyValues arrays.

argCustomPropertyKeys—See the description in the “Custom Properties” section on page 2-10.

argCustomPropertyValues—See the description in the “Custom Properties” section on page 2-10.

argPropertySize—Size of the argCustomPropertyKeys and argCustomPropertyValues arrays.

argDomain—See the description in the “Subscriber Domains” section on page 2-9.

A NULL value indicates that the subscriber does not have a domain.

Return Value



OL-31824-01

Chapter 3 Blocking API removeSubscriber

Error Codes

The following list provides the error codes that the addSubscriber method might return:





• ERROR_CODE_UNKNOWN

This error code indicates that invalid values were supplied for the propertyValues parameter.


Example

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

char* propKeys[] = { "work_phone", "home_phone" };char *propValues[] = { "123456", "898765" };

bapi.addSubscriber( "alpha", NULL, NULL, 0,// dynamic mappings will be set by login NULL, NULL, 0,// dynamic properties will be set by login propKeys, propValues, 2,// 2 custom properties "subscribers"); // default domain

To add a new IPv6 subscriber, alpha, with custom properties:

char* propKeys[] = { "work_phone", "home_phone" };char *propValues[] = { "123456", "898765" };

bapi.addSubscriber( "alpha", NULL, NULL, 0,// dynamic mappings will be set by login NULL, NULL, 0,// dynamic properties will be set by login propKeys, propValues, 2,// 2 custom properties "subscribers"); // default domain

removeSubscriberThe following sections provide information about the removeSubscriber operation:








OL-31824-01

Chapter 3 Blocking API removeAllSubscribers

Syntax

The removeSubscriber syntax is as follows:

ReturnCode* removeSubscriber(char* argName)

Description

The removeSubscriber method removes a subscriber completely from the Cisco Service Control Subscriber Manager database.

Parameters


Return Value


• TRUE—If the subscriber was found in the database and successfully removed.

• FALSE—If the conditions for TRUE were not met; that is, the subscriber was not found in the database, or the subscriber was found but was not successfully removed.

Error Codes

The following list provides error codes that this method might return:


• ERROR_CODE _SUBSCRIBER_DOES_NOT_EXIST



Example

To remove subscriber alpha entirely from the database:

bapi.removeSubscriber("alpha");

removeAllSubscribersThe following sections provide information about the removeAllSubscribers operation:






OL-31824-01

Chapter 3 Blocking API getNumberOfSubscribers

Syntax

The removeAllSubscribers syntax is as follows:

ReturnCode* removeAllSubscribers()

Description

The removeAllSubscribers method removes all subscribers from the Cisco Service Control Subscriber Manager, leaving the database with no subscribers.

Note This method might take time to execute. To avoid operation timeout exceptions, set a high operation timeout (up to five minutes) before calling this method.

Return Value


Error Codes

None.

getNumberOfSubscribersThe following sections provide information about the getNumberOfSubscribders operation:





Syntax

The getNumberOfSubscribders syntax is as follows:

ReturnCode* getNumberOfSubscribers()

Description

The getNumberOfSubscribders method retrieves the total number of subscribers in the Subscriber Manager database.

Return Value

The return value is a pointer to a ReturnCode structure holding an integer that indicates the number of subscribers in the Cisco Service Control Subscriber Manager.


OL-31824-01

Chapter 3 Blocking API getNumberOfSubscribersInDomain

Error Codes

None.

getNumberOfSubscribersInDomainThe following sections provide information about the getNumberOfSubscribersInDomain operation:






Syntax

The getNumberOfSubscribersInDomain syntax is as follows:

ReturnCode* getNumberOfSubscribersInDomain(char* argDomain)

Description

The getNumberOfSubscribersInDomain method retrieves the number of subscribers in a subscriber domain.

Parameters

argDomain—Name of a subscriber domain that exists in the domain repository of the Subscriber Manager.

Return Value

The return value is a pointer to a ReturnCode structure holding an integer that indicates the number of subscribers in the domain provided.

Error Codes

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


• ERROR_CODE _DOMAIN_NOT_FOUND



OL-31824-01

Chapter 3 Blocking API getSubscriber

getSubscriberThe following sections provide information about the getSubscriber operation:







Syntax

The getSubscriber syntax is as follows:

ReturnCode* getSubscriber(char* argName)

Description

The getSubscriber method retrieves a subscriber record. Each field is formatted as an integer, string, or string array, as described in the Return Value section. If the subscriber does not exist in the Subscriber Manager database, an exception is thrown.

Parameters


Return Value

The return value is a pointer to a ReturnCode structure holding an array of ReturnCode structures with nine elements. There is no array value that is NULL.

Table 3-1 lists the element values and their meanings.

Table 3-1 Element Values and Meanings

Element Value Meaning

Index 0 Subscriber name (char*)

Index 1 Array of mappings (char**)

Index 2 Array of mapping types (short*)

Index 3 Domain name (char*)

Index 4 Array of property names (char**)

Index 5 Array of property values (char**)

Index 6 Array of custom property names (char**)


OL-31824-01

Chapter 3 Blocking API subscriberExists

Error Codes





Example

To retrieve the subscriber record of alpha:

ReturnCode* sub = bapi.getSubscriber("alpha");// sub namechar* name = sub->u.objectArray[0]->u.stringVal;

// sub mappingchar** mappings = sub->u.objectArray[1]->u.stringArrayVal;

// mappings typesshort* types = sub->u.objectArray[2]->u.shortArrayVal;

char* domainName = (char*)sub->u.objectArray[3]->u.stringVal;

char** propertyNames = (char**)sub->u.objectArray[4]->u.stringArrayVal;

char** propertyValues = (char**)sub->u.objectArray[5]->u.stringArrayVal;

char** customPropertyName = (char**)sub->u.objectArray[6]->u.stringArrayVal;

char** customPropertyValues = (char**)sub->u.objectArray[7]->u.stringArrayVal;

long* autoLogoutTime = sub->u.objectArray[8]->u.longArrayVal;

subscriberExistsThe following sections provide information about the subscriberExists operation:






Index 7 Array of custom property values (char**)

Index 8 Array of auto-logout time, as seconds from now, or value of -1 if not set (long 1*) one per mapping (index1)

Table 3-1 Element Values and Meanings (continued)

Element Value Meaning


OL-31824-01

Chapter 3 Blocking API subscriberLoggedIn

Syntax

The subscriberExists syntax is as follows:

ReturnCode* subscriberExists(char* argName)

Description

The subscriberExists method verifies that a subscriber exists in the Cisco Service Control Subscriber Manager database.

Parameters


Return Value


• TRUE—If the subscriber was found in the Cisco Service Control Subscriber Manager database.

• FALSE—If the subscriber could not be found.

Error Codes

None.

subscriberLoggedInThe following sections provide information about the subscriberLoggedIn operation:






Syntax

The subscriberLoggedIn syntax is as follows:

ReturnCode* subscriberLoggedIn(char* argName)

Description

The subscriberLoggedIn method checks whether a subscriber that already exists in the Cisco Service Control Subscriber Manager database is logged in; that is, if the subscriber also exists in an SCE database.


OL-31824-01

Chapter 3 Blocking API getSubscriberNameByMapping

When the Cisco Service Control Subscriber Manager 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 Cisco Service Control Subscriber Manager database, an exception is thrown.

Parameters


Return Value


• TRUE—If the subscriber is logged in.

• FALSE—If the subscriber is not logged in.

Error Codes

The following list provides error codes that this method might return:




getSubscriberNameByMappingThe following sections provide information about the getSubscriberNameByMapping operation:






Syntax

The getSubscriberNameByMapping syntax is as follows:

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

Description

The getSubscriberNameByMapping method finds a subscriber name according to a mapping and a domain.


OL-31824-01

Chapter 3 Blocking API getSubscriberNames (all)

Parameters

argMapping—See the description in the “Network ID Mappings” section on page 2-7.

argMappingType—See the description in the “Network ID Mappings” section on page 2-7.

argDomain—Name of the domain to which the subscriber belongs.

The operation fails if either of the following conditions exists:

• The domain is null, but the subscriber exists in the database and belongs to a domain.

• The specified domain is incorrect.

Return Value

The return value is a pointer to a ReturnCode structure with a String (char*) type:

• Subscriber name—If a subscriber record was found.

• NULL—If no subscriber record with the supplied mapping could be found in the Cisco Service Control Subscriber Manager database.

Error Codes

The following list presents error codes that this method might return:






getSubscriberNames (all)The following sections provide information about the getSubscriberNames (all) operation:







Syntax

The getSubscriberNames (all) syntax:

ReturnCode* getSubscriberNames(char* argFirstName, int argAmount)


OL-31824-01

Chapter 3 Blocking API getSubscriberNames (all)

Description

The getSubscriberNames (all) method retrieves a bulk of subscriber names from the Cisco Service Control Subscriber Manager database, starting with argFirstName, followed by the next argAmount subscribers (in alphabetical order).

If argFirstName is NULL, the first subscriber name (alphabetically) that exists in the Cisco Service Control Subscriber Manager database is used.

Note There is no guarantee that the total number of subscribers (in all the bulks) equals the value returned from getNumOfSubscribers at any time. The values differ if some subscribers are added or removed while the bulks are being retrieved.

Parameters

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

argAmount—The limit on the number of subscribers that is returned. If this value is higher than the Cisco Service Control Subscriber Manager limit (1000), the Cisco Service Control Subscriber Manager limit is used.

Note Do not retrieve a value of more than 500 subscribers.

Return Value

The return value is a pointer to a ReturnCode structure with a string array (char**) holding a list of subscriber names alphabetically ordered.

The getSubscriberNames (all) method returns all the subscribers found in the Cisco Service Control Subscriber Manager database, starting at the requested subscriber. The array size is limited by the smaller of the values between argAmount and the Cisco Service Control Subscriber Manager limit (1000).

Error Codes





Example

To receive an alphabetical list of subscriber names:

bool hasMoreSubscribers;char* lastBulkEnd = NULL;char tmpName[50];int bulkSize = 100;


OL-31824-01

Chapter 3 Blocking API getSubscriberNames (filter by property)

do{ ReturnCode* subscribers = smApi.getSubscriberNames(lastBulkEnd,bulkSize);

hasMoreSubscribers = false;

if ((isReturnCodeError(subscribers) == false) && (subscribers->type == STRING_ARRAY_T) && (subscribers->u.stringArrayVal != NULL)) {

for (int i = 0; i < subscribers->size; i++) { // do something with subscribers->u.stringArrayVal[i] }

if (subscribers->size == bulkSize) { hasMoreSubscribers = true; strcpy (tmpName, subscribers->u.stringArrayVal[bulkSize - 1]); lastBulkEnd = tmpName; } } freeReturnCode(subscribers);

} while (hasMoreSubscribers);

getSubscriberNames (filter by property)The following sections provide information about getSubscriberNames (filter by property):






Syntax

The getSubscriberNames (filter by property) syntax:

ReturnCode* getSubscriberNames(char* lastBulkEnd, char* propName, char* propValue, int numOfSubscribers)

Description

The getSubscriberNames (filter by property) method retrieves a bulk of subscriber names from the Cisco Service Control Subscriber Manager database, starting with lastBulkEnd, followed by numOfSubscribers (in alphabetical order), and based on the property name and property value.

If lastBulkEnd is NULL, the first subscriber name (alphabetically) that exists in the Cisco Service Control Subscriber Manager database is used.


OL-31824-01

Chapter 3 Blocking API getSubscriberNamesInDomain

Note There is no guarantee that the total number of subscribers (in all the bulks) equals the value returned from getNumOfSubscribers at any time. The values might differ if some subscribers are added or removed when the bulks are being retrieved.

Parameters

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

propName—The property name of the character string array used to filter subscriber names.

propValue—The property value of the character string array used to filter subscriber names.

numOfSubscribers—The limit on the number of subscribers that is returned. If this value is higher than the Cisco Service Control Subscriber Manager limit (1000), the Cisco Service Control Subscriber Manager limit is used.

Note Do not retrieve a value of more than 500 subscribers.

Return Value

The return value is a pointer to a ReturnCode structure with a string array (char**) holding a list of alphabetically ordered subscriber names that match the property name and its provided value.

The getSubscriberNames (filter by property) method returns all the subscribers found in the Cisco Service Control Subscriber Manager database, starting at the requested subscriber. The array size is limited by the smaller of the values between numOfSubscribers and the Cisco Service Control Subscriber Manager limit (1000).

Error Codes

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



getSubscriberNamesInDomainThe following sections provide information about the getSubscriberNamesInDomain operation:







OL-31824-01

Chapter 3 Blocking API getSubscriberNamesInDomain

Syntax

The getSubscriberNamesInDomain syntax:

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

Description

The getSubscriberNamesInDomain method retrieves subscribers that are associated with the specified domain from the Cisco Service Control Subscriber Manager database.

The getSubscriberNamesInDomain operation functions in the same way as the getSubscriberNames (all) operation described in the “getSubscriberNames (all)” section on page 3-26.

Parameters

argFirstName—See the description in the “Parameters” section on page 3-27 of the getSusbcriberNames (all) operation.

argAmount—See the description in the “Parameters” section on page 3-27 of the getSusbcriberNames (all) operation.

argDomain—The name of a subscriber domain that exists in the Cisco Service Control Subscriber Manager domain repository.

Return Value

The return value is an alphabetically ordered array of subscriber names that belong to the specified domain.

For more information, see the “Return Value” section on page 3-27 of the getSusbcriberNames (all) operation.

Error Codes



• ERROR_CODE _DOMAIN_NOT_FOUND




OL-31824-01

Chapter 3 Blocking API getSubscriberNamesWithPrefix

getSubscriberNamesWithPrefixThe following sections provide information about the getSubscriberNamesWithPrefix operation:






Syntax

The getSubscriberNamesWithPrefix syntax is as follows:

ReturnCode* getSubscriberNamesWithPrefix(char* argFirstName, int argAmount, char* argPrefix)

Description

The getSubscriberNamesWithPrefix method retrieves subscribers from the Cisco Service Control Subscriber Manager database whose names begin with a specified prefix.

The function of this operation is the same as the getSubscriberNames (all) operation described in the “getSubscriberNames (all)” section on page 3-26.

Parameters



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

Return Value

The return value is an alphabetically ordered array of subscriber names that start with the required prefix. See the “Return Value” section on page 3-27 of the getSusbcriberNames (all) operation.

Error Codes






OL-31824-01

Chapter 3 Blocking API getSubscriberNamesWithSuffix

getSubscriberNamesWithSuffixThe following sections provide information about the getSubscriberNamesWithSuffix operation:






Syntax

The getSubscriberNamesWithSuffix syntax is as follows:

ReturnCode* getSubscriberNamesWithSuffix(char* argFirstName, int argAmount, char* argSuffix)

Description

The getSubscriberNamesWithSuffix method retrieves subscribers from the Cisco Service Control Subscriber Manager database whose names end with the specified suffix.

The function of this operation is the same as the getSubscriberNames (all) operation as described in the “getSubscriberNames (all)” section on page 3-26.

Parameters



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

Return Value

The return value is an alphabetically ordered array of subscriber names that end with the required suffix. See the “Return Value” section on page 3-27 of the getSusbcriberNames operation.

Error Codes






OL-31824-01

Chapter 3 Blocking API getDomains

getDomainsThe following sections provide information about the getDomains operation:





Syntax

The getDomains syntax is as follows:

ReturnCode* getDomains()

Description

The getDomains method provides a list of current subscriber domains in the Cisco Service Control Subscriber Manager domain repository.

Return Value

A pointer to a ReturnCode structure with a string array (char**) holding a complete list of subscriber domain names in the Cisco Service Control Subscriber Manager.

Error Codes

None.

setPropertiesToDefaultThe following sections provide information about the setPropertiesToDefault operation:






Syntax

The setPropertiesToDefault syntax is as follows:

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


OL-31824-01

Chapter 3 Blocking API removeCustomProperties

Description

The setPropertiesToDefault method resets the specified application properties of a subscriber. If an application is installed, the relevant application properties are 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.

Parameters


argPropertyKeys—See the description in the “Subscriber Properties” section on page 2-10.

argPropertySize—Size of the argPropertyKeys array.

Return Value


Error Codes

The following list provides the error codes that the setPropertiesToDefault method might return:





removeCustomPropertiesThe following sections provide information about the removeCustomProperties operation:






Syntax

The removeCustomProperties syntax is a s follows:

ReturnCode* removeCustomProperties(char* argName, char** argCustomPropertyKeys, int argCustomPropertySize)

Description

The removeCustomProperties method resets the specified custom properties of a subscriber.


OL-31824-01

Chapter 3 Blocking API C++ setLogger Method

Parameters


argCustomPropertyKeys—See the description in the “Custom Properties” section on page 2-10.

argCustomPropertySize—Size of the argCustomPropertyKeys array.

Return Value


Error Codes

The following list provides the error codes that removeCustomProperties method might return:


• ERROR_CODE _SUBSCRIBER_DOES_NOT_EXIST



C++ setLogger MethodThe following sections provide information about the C++ setLogger method operation:





Syntax

The C++ setLogger syntax is a s follows:

void setLogger(Logger *argLogger)

Description

The C++ setLogger method sets an implementation of the abstract Logger class. Use this method to integrate the Cisco Service Control Subscriber Manager API log messages with the host application log.

Parameters

argLogger—Implementation of the abstract Logger class.

Return Value

None.


OL-31824-01

Chapter 3 Blocking API C++ init Method

C++ init MethodThe following sections provide information about the C++ init method operation:






Syntax

The C++ init syntax is as follows:

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

Description

The C++ init Method configures and initializes the API.

Note This method must be called before performing any operation of the C++ API.

Parameters

argSupportedThreads—Number of threads the API should support.

argThreadPriority—Priority for the PRPC protocol network thread.

argBufferSize—Internal buffer size (set 2,000,000 bytes as default value).

argKeepAliveDuration—Hint about the desired delay between PRPC protocol keepalive messages (set 10 seconds as default value).

argConnectionTimeout—Hint about the desired timeout on a non-responding PRPC protocol connection (set 20 seconds as default value).

argReconnectTimeout—Timeout after which the API attempts to re-establish the connection to Cisco Service Control Subscriber Manager.

Return Value

The return value is a Boolean value:

• TRUE—Success

• FALSE—Fail


OL-31824-01

Chapter 3 Blocking API C SMB_init Function

Example

SmBlockingApi bapi;bool success = bapi.init(10, 0, 2000000, //default 10, //default 20, //default 0); //default (no reconnect)

C SMB_init FunctionThe following sections provide information about the C SMB_init function:






Syntax

The C SMB_init function syntax is as follows:

SMB_HANDLE SMB_init (int argSupportedThreads, int argThreadPriority, Uint32 argBufferSize, Uint32 argKeepAliveDuration, Uint32 argConnectionTimeout)

Description

The C SMB_init function allocates, configures, and initializes the API.

Note This method must be called before performing any operation of the C API.

Parameters

argSupportedThreads—Number of threads the API should support.

argThreadPriority—Priority for the PRPC protocol network thread.

argBufferSize—Internal buffer size (set 2,000,000 bytes as default value).

argKeepAliveDuration—Hint about the desired delay between PRPC protocol keepalive messages (set 10 seconds as default value).

argConnectionTimeout—Hint about the desired timeout on a non-responding PRPC protocol connection (set 20 seconds as default value).


OL-31824-01

Chapter 3 Blocking API C SMB_release Function

Return Value

The return values is an SMB_HANDLE handle to the API. A NULL handle means the initialization has failed.

Example

SMB_HANDLE api;// initialize an APIapi = SMB_init(10, // 10 threads 0, 300000, // 3,000,000 bytes 10, // default 30); // 30 sec connection timeout

C SMB_release FunctionThe following sections provide information about the C SMB_release Function operation:





Syntax

The C SMB_release function syntax is as follows:

void SMB_release(SMB_HANDLE argApiHandle)

Description

The C SMB_release function releases the resources used by the API. This function must be called at the end of the use of the API.

Parameters

argApiHandle—API handle received by using the SMB_init function.

Return Value

None.

setReconnectTimeoutThe following sections provide information about the setReconnectTimeout operation:




OL-31824-01

Chapter 3 Blocking API setName



Syntax

The setReconnectTimeout syntax is as follows:

void setReconnectTimeout(Uint32 reconnectTimeout)

Description

The setReconnectTimeout method sets the reconnection timeout.

When the connection to the Cisco Service Control Subscriber Manager is down, the API attempts to re-establish the connection after “reconnection timeout” seconds.

Parameters

reconnectTimeout—The reconnection timeout in seconds.

Return Value

None.

setNameThe following sections provide information about the setName operation:





Syntax

The setName syntax is as follows:

void setName(char *argName)

Description

The setName method sets the name of the API. This name serves as a unique identifier for the API-Cisco Service Control Subscriber Manager connection. The setName function should be called before calling the connect method.

Parameters

argName—The name of the API,


OL-31824-01

Chapter 3 Blocking API connect

Return Value

None.

connectThe following sections provide information about the connect operation:





Syntax

The connect syntax is as follows:

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

Description

The connect method attempts to establish a PRPC protocol connection to the Cisco Service Control Subscriber Manager.

Parameters

argHostName—IP address of the Cisco Service Control Subscriber Manager or the name of the host.

argPort—TCP port to be used to connect the Cisco Service Control Subscriber Manager (default is 14374).

Return Value


• TRUE—Success

• FALSE—Fail

disconnectThe following sections provide information about the disconnect operation:





OL-31824-01

Chapter 3 Blocking API isConnected

Syntax

The disconnect syntax is as follows:

bool disconnect()

Description

The disconnect method attempts to terminate the PRPC protocol connection to the Cisco Service Control Subscriber Manager.

Return Value


• TRUE—Success

• FALSE—Fail

isConnectedThe following sections provide information about the isConnected operation:




Syntax

The isConnected syntax is as follows:

bool isConnected();

Description

The isConnected method checks whether the PRPC protocol connection to the Cisco Service Control Subscriber Manager is operating.

Return Value


• TRUE—The connection is up.

• FALSE—The connection is down.


OL-31824-01

Chapter 3 Blocking API Blocking API C++ Code Examples

Blocking API C++ Code ExamplesThis section provides two code examples:

• Getting Number of Subscribers, page 3-42

• Adding a Subscriber, Printing Information, and Removing a Subscriber, page 3-43

Getting Number of SubscribersThe following example prints to standard output (stdout) the total number of subscribers in the Cisco Service Control Subscriber Manager database and the number of subscribers in each subscriber domain:

#include "SmApiBlocking.h"#include <stdio.h>

int main(int argc, char* argv[]){ SmApiBlocking bapi; //initiation bapi.init(); bapi.setReplyTimeout(300000); //set timeout for 5 minutes bapi.connect(argv[1]); // connect to the SM //operations ReturnCode* domains = bapi.getDomains(); ReturnCode* totalSubscribers=bapi.getNumberOfSubscribers(); if ((isReturnCodeError(domains) == false) && (isReturnCodeError(totalSubscribers) == false)) { printf("number of susbcribers in the database:\t\t %d\n", totalSubscribers->u.intVal); for (int i=0; i<domains->size; i++) { ReturnCode* numberOfSusbcribersInDomain= bapi.getNumberOfSubscribersInDomain( domains->u.stringArrayVal[i]); if (isReturnCodeError(numberOfSusbcribersInDomain) == false) { printf("number of susbcribers domain %s:\t\t%d\n", domains->u.stringArrayVal[i], numberOfSusbcribersInDomain->u.intVal); } freeReturnCode (numberOfSusbcribersInDomain); } } freeReturnCode (domains); freeReturnCode (totalSubscribers); //finalization bapi.disconnect(); return 0;}


OL-31824-01

Chapter 3 Blocking API Adding a Subscriber, Printing Information, and Removing a Subscriber

Adding a Subscriber, Printing Information, and Removing a SubscriberThe following program adds an IPv4 subscriber to the subscriber database, retrieves the subscriber information, prints it to standard output (stdout), and removes the subscriber from the subscriber database:

#include "SmApiBlocking.h"#include <stdio.h>int main(int argc, char* argv[]){ checkArguments(argc,argv); SmApiBlocking bapi; //initiation bapi.init(); bapi.setReplyTimeout(10000); //set timeout for 10 seconds bapi.connect(argv[1]); // connect to the SM //add subscriber printf("adding subscriber to SM\n"); MappingType type = IP_RANGE; char* customKey = "custom-key"; char* customVal = "10"; ReturnCode* ret = bapi.addSubscriber( argv[2], // name &(argv[3]), // mapping &type, // mapping type 1, // one mapping &(argv[4]), // property key &(argv[5]), // property value 1, // number of properties &customKey, // custom property key &customVal, // custom property value 1, // number of custom properties argv[6]); // domain freeReturnCode (ret);

//Print subscriber printf("Printing subscriber:\n"); ReturnCode* subfields = bapi.getSubscriber(argv[1]); if (isReturnCodeError(subfields) == false) { printf("\tname:\t\t%s\n", subfields->u.objectArray[0]->u.stringVal); printf("\tmapping:\t%s\n", subfields->u.objectArray[1]->u.stringArrayVal[0]); printf("\tdomain:\t\t%s\n", subfields->u.objectArray[3]->u.stringVal); printf("\tautologout:\t%d\n", subfields->u.objectArray[8]->u.intVal); // Remove subscriber printf("removing subscriber from SM\n"); bapi.removeSubscriber(argv[1]); } else { printf("error in subscriber retrieval\n"); } freeReturnCode(subfields); //finalization bapi.disconnect(); return 0;}

void checkArguments(int argc, char* argv[]){if (argc != 7) { printf("usage: AddPrintRemove <SM-address> <subscriber-name> "


OL-31824-01


"<IP mapping> <property-key> <property-value> <domain>"); exit(1); }}

The following program adds an IPv6 subscriber to the subscriber database, retrieves the subscriber information, prints it to standard output (stdout), and removes the subscriber from the subscriber database:

#include "SmApiBlocking.h"#include <stdio.h>int main(int argc, char* argv[]){

checkArguments(argc,argv);SmApiBlocking bapi;//initiationbapi.init();bapi.setReplyTimeout(10000); //set timeout for 10 secondsbapi.connect(argv[1]); // connect to the SM//add subscriberprintf("adding subscriber to SM\n");MappingType type = TYPE_IPV6;char* customKey = "custom-key";char* customVal = "10";ReturnCode* ret = bapi.addSubscriber(argv[2], // name&(argv[3]), // mapping&type, // mapping type1, // one mapping&(argv[4]), // property key&(argv[5]), // property value1, // number of properties&customKey, // custom property key&customVal, // custom property value1, // number of custom propertiesargv[6]); // domainfreeReturnCode (ret);//Print subscriberprintf("Printing subscriber:\n");ReturnCode* subfields = bapi.getSubscriber(argv[2]);if (isReturnCodeError(subfields) == false){

printf("\tname:\t\t%s\n", subfields->u.objectArray[0]->u.stringVal);printf("\tmapping:\t%s\n", subfields->u.objectArray[1]->u.stringArrayVal[0]);printf("\tdomain:\t\t%s\n", subfields->u.objectArray[3]->u.stringVal);printf("\tautologout:\t%d\n", subfields->u.objectArray[8]->u.intVal);// Remove subscriberprintf("removing subscriber from SM\n");bapi.removeSubscriber(argv[2]);

}else{

printf("error in subscriber retrieval\n");}freeReturnCode(subfields);//finalizationbapi.disconnect();return 0;

}

void checkArguments(int argc, char* argv[]){

if (argc != 7)


OL-31824-01

Chapter 3 Blocking API Blocking API C Code Examples

{printf("usage: AddPrintRemove <SM-address> <subscriber-name> ""<IPV6 mapping> <property-key> <property-value> <domain>");exit(1);

}}

Blocking API C Code ExamplesThis section provides two code examples:

• Getting Number of Subscribers, page 3-45

• Adding a Subscriber, Printing Information, and Removing a Subscriber, page 3-46

Getting Number of SubscribersThe following example prints to standard output (stdout) the total number of subscribers in the Cisco Service Control Subscriber Manager database and the number of subscribers in each subscriber domain:

#include "SmApiBlocking_c.h"#include <stdio.h>

int main(int argc, char* argv[]){ //initiation SMB_HANDLE bapi = SMB_init(10,0,2000000,10,20); if (bapi == NULL) { // init failure return -1; } SMB_setReplyTimeout(bapi,300000); //set timeout for 5 minutes SMB_connect(bapi,argv[1],14374); // connect to the SM //operations ReturnCode* domains = SMB_getDomains(bapi); ReturnCode* totalSubscribers= SMB_getNumberOfSubscribers(bapi); if ((isReturnCodeError(domains) == false) && (isReturnCodeError(totalSubscribers) == false)) { printf("number of susbcribers in the database:\t\t %d\n", totalSubscribers->u.intVal); for (int i=0; i<domains->size; i++) { ReturnCode* numberOfSusbcribersInDomain= SMB_getNumberOfSubscribersInDomain(bapi, domains->u.stringArrayVal[i]); if(isReturnCodeError(numberOfSusbcribersInDomain) == false { printf("number of susbcribers domain %s:\t\t%d\n", domains->u.stringArrayVal[i], numberOfSusbcribersInDomain->u.intVal); } freeReturnCode (numberOfSusbcribersInDomain); } } freeReturnCode (domains); freeReturnCode (totalSubscribers); //finalization SMB_disconnect(bapi);


OL-31824-01


SMB_release(bapi); return 0;}

Adding a Subscriber, Printing Information, and Removing a SubscriberThe following program adds a subscriber to the subscriber database, retrieves the subscriber information, prints it to standard output (stdout), and removes the subscriber from the subscriber database:

#include "SmApiBlocking_c.h"#include <stdio.h>int main(int argc, char* argv[]){ checkArguments(argc,argv);

//initiation SMB_HANDLE bapi = SMB_init(10,0,2000000,10,20); if (bapi == NULL) { // init failure return -1; } SMB_setReplyTimeout(bapi,10000); //set timeout for 10 seconds SMB_connect(bapi,argv[1], 14374);// connect to the SM //add subscriber printf("adding subscriber to SM\n"); MappingType type = IP_RANGE; char* customKey = "custom-key"; char* customVal = "10"; ReturnCode* ret = SMB_addSubscriber( bapi, // handle argv[2], // name &(argv[3]), // mapping` &type, // mapping type 1, // one mapping &(argv[4]), // property key &(argv[5]), // property value 1, // number of properties &customKey, // custom property key &customVal, // custom property value 1, // number of custom properties argv[6]); // domain freeReturnCode (ret);

//Print subscriber printf("Printing subscriber:\n"); ReturnCode* subfields = SMB_getSubscriber(bapi,argv[2]); if (isReturnCodeError(subfields) == false) { printf("\tname:\t\t%s\n", subfields->u.objectArray[0]->u.stringVal); printf("\tmapping:\t%s\n", subfields->u.objectArray[1]->u.stringArrayVal[0]); printf("\tdomain:\t\t%s\n", subfields->u.objectArray[3]->u.stringVal); printf("\tautologout:\t%d\n", subfields->u.objectArray[8]->u.intVal); // Remove subscriber printf("removing subscriber from SM\n"); SMB_removeSubscriber(bapi,argv[2]); } else { printf("error in subscriber retrieval\n"); } freeReturnCode(subfields);


OL-31824-01


//finalization SMB_disconnect(bapi); SMB_release(bapi); return 0;}

void checkArguments(int argc, char* argv[]){ if (argc != 7) { printf("usage: AddPrintRemove <SM-address> <subscriber-name> " "<IP mapping> <property-key> <property-value> <domain>"); exit(1); }}

The following program adds a subscriber to the subscriber database, retrieves the subscriber information, prints it to standard output (stdout), and removes the subscriber from the subscriber database:

#include "SmApiBlocking_c.h"#include <stdio.h>int main(int argc, char* argv[]){

checkArguments(argc,argv);//initiationSMB_HANDLE bapi = SMB_init(10,0,2000000,10,20);if (bapi == NULL){

// init failurereturn -1;

}SMB_setReplyTimeout(bapi,10000); //set timeout for 10 secondsSMB_connect(bapi,argv[1], 14374);// connect to the SM//add subscriberprintf("adding subscriber to SM\n");MappingType type = TYPE_IPV6;char* customKey = "custom-key";char* customVal = "10";ReturnCode* ret = SMB_addSubscriber(bapi, // handleargv[2], // name&(argv[3]), // mapping`&type, // mapping type1, // one mapping&(argv[4]), // property key&(argv[5]), // property value1, // number of properties&customKey, // custom property key&customVal, // custom property value1, // number of custom propertiesargv[6]); // domainfreeReturnCode (ret);//Print subscriberprintf("Printing subscriber:\n");ReturnCode* subfields = SMB_getSubscriber(bapi,argv[2]);if (isReturnCodeError(subfields) == false){

printf("\tname:\t\t%s\n", subfields->u.objectArray[0]->u.stringVal);printf("\tmapping:\t%s\n", subfields->u.objectArray[1]->u.stringArrayVal[0]);printf("\tdomain:\t\t%s\n", subfields->u.objectArray[3]->u.stringVal);printf("\tautologout:\t%d\n", subfields->u.objectArray[8]->u.intVal);// Remove subscriberprintf("removing subscriber from SM\n");SMB_removeSubscriber(bapi,argv[2]);


OL-31824-01


}else{

printf("error in subscriber retrieval\n");}freeReturnCode(subfields);//finalizationSMB_disconnect(bapi);SMB_release(bapi);return 0;

}

void checkArguments(int argc, char* argv[]){

if (argc != 7){

printf("usage: AddPrintRemove <SM-address> <subscriber-name> ""<IPV6 mapping> <property-key> <property-value> <domain>");exit(1);

}}


OL-31824-01


C H A P T E R 4
Nonblocking API

IntroductionThis chapter describes the features and operations of the Nonblocking API and provides code examples. It also introduces the result handler callbacks, a feature unique to the Nonblocking API.

• Multithreading Support, page 4-1

• Result Handler Callbacks, page 4-1

• Nonblocking API Methods, page 4-3

• Nonblocking API C++ Code Examples, page 4-8

• Nonblocking API C Code Examples, page 4-14

Multithreading SupportThe Nonblocking API supports an unlimited number of threads calling its methods simultaneously.

Note In a multithreaded scenario for the Nonblocking API, the order of invocation is guarenteed. The API performs operations in the same chronological order in which they are called.

Result Handler CallbacksThe Nonblocking API enables you to set result handler callbacks. The result handler callbacks are two functions for handleSuccess and handleError, as shown in the following code:

/* operation failure callback specification */typedef void (*OperationFailCallBackFunc)(Uint32 argHandle, ReturnCode *argReturnCode);

/* operation success callback specification */typedef void (*OperationSuccessCallBackFunc)(Uint32 argHandle, ReturnCode *argReturnCode);


Chapter 4 Nonblocking API Result Handler Callbacks Example

You should implement these callbacks if you want to be informed about the success or error results of operations performed by using the API.

Note This is the only interface for retrieving results. Results cannot be returned immediately after the API method has returned to the caller.

Both handleSuccess and handleError callbacks accept two parameters:

• Handle—The return value of each operation is a handle of type Uint32. This handle enables correlation of operation calls and their results. When a handle... operation is called with a handle of value X, the result matches the operation that returned the same handle value (X) to the caller.

• Result—The actual result of the operation returned as a pointer of type ResultCode.

Result Handler Callbacks ExampleThe following example is a basic implementation of a result handler that counts the number of success or failure operations. The result handler method initiates the API and assigns a result handler.

For correct operation of the result handler, follow the code sequence given in the following example.

Note This example does not demonstrate the use of callback handles.

#include "GeneralDefs.h"#include "SmApiNonBlocking.h"#include <stdio.h>

int successCnt = 0;int failCnt = 0;

void onOperationFail(Uint32 argHandle, ReturnCode* argReturnCode){ failCnt++; if (argReturnCode != NULL) { freeReturnCode(argReturnCode); }}

void onOperationSuccess(Uint32 argHandle, ReturnCode* argReturnCode){ successCnt++; if (argReturnCode != NULL) { freeReturnCode(argReturnCode); }}

int main(int argc, char* argv[]){ if (argc != 2) { printf("usage: ResultHandlerExample <sm-ip>"); exit(1); }


OL-31824-01

Chapter 4 Nonblocking API Nonblocking API Methods

//note the order of operations! SmApiNonBlocking nbapi; nbapi.init(); nbapi.connect(argv[1]); nbapi.setReplyFailCallBack(onOperationFail); nbapi.setReplySuccessCallBack(onOperationSuccess); nbapi.login(...); ...

nbapi.disconnect();

return 0;}

Nonblocking API MethodsThis section lists the methods of the Nonblocking API.

Some of the methods return a non-negative int handle that can be used to correlate operation calls and their results (see the “Result Handler Callbacks” section on page 4-1). If an internal error occurred, a negative value is returned and the operation is not performed.

The operation results passed to the result handler callbacks are the same as the return values described in the same method in the Blocking API section (see the “Blocking API” section on page 3-1), except that return values of void are translated to NULL.

Note The error and fail callback is handed with an error only if the matching operation in the Blocking API would return an error code with the same arguments according to the Cisco Service Control Subscriber Manager database state at the time of the call.

The C and C++ API share the same function signature, except for SMNB_ prefix for all Nonblocking C APIs function names, and an API handle of type SMNB_HANDLE as the first parameter in all functions. The function description indicates any other differences between the APIs.

The following methods are described:

• login, page 4-4

• logoutByName, page 4-4

• logoutByNameFromDomain, page 4-4

• logoutByMapping, page 4-5

• loginCable, page 4-5

• logoutCable, page 4-5

• C++ setLogger Method, page 4-6

• C++ init Method, page 4-6

• C SMNB_init Function, page 4-6

• C SMNB_release Function, page 4-7

• setReconnectTimeout, page 4-7

• setName, page 4-7

• connect, page 4-7


OL-31824-01

Chapter 4 Nonblocking API login

• disconnect, page 4-8

• isConnected, page 4-8

loginThe following section provides login operation syntax information.

Syntax

The login syntax:

int login(char* argName, char** argMappings, MappingType* argMappingTypes, int argMappingsSize, char** argPropertyKeys, char** argPropertyValues, int argPropertySize, char* argDomain, bool argIsAdditive, int argAutoLogoutTime)

The operation functionality is the same as the matching Blocking API operation. See the “login” section on page 3-4 for more information.

logoutByNameThe following section provides information about the logoutByName operation syntax.

Syntax

The logoutByName syntax is as follows:

int logoutByName(char* argName, char** argMappings, MappingType* argMappingTypes, int argMappingsSize)

The operation functionality is the same as the matching Blocking API operation. See the “logoutByName” section on page 3-8 for more information.

logoutByNameFromDomainThe following section provides information about the logoutByNameFromDomain operation syntax.

Syntax

The logoutByNameFromDomain syntax is as follows:

int logoutByNameFromDomain (char* argName, char** argMappings, MappingType* argMappingTypes,


OL-31824-01

Chapter 4 Nonblocking API logoutByMapping

int argMappingsSize, char* argDomain)

The operation functionality is the same as the matching Blocking API operation. See the “logoutByNameFromDomain” section on page 3-10 for more information.

logoutByMappingThe following section provides information about the logoutByMapping operation syntax.

Syntax

The logoutByMapping syntax is as follows:

int logoutByMapping(char* argMapping, MappingType argMappingType, char* argDomain)

The operation functionality is the same as the matching Blocking API operation. See the “logoutByMapping” section on page 3-12 for more information.

loginCableThe following section provides information about the loginCable operation syntax.

Syntax

The loginCable syntax is as follows:

int loginCable(char* argCpe, char* argCm, char* argIp, int argLease, char* argDomain, char** argPropertyKeys, char** argPropertyValues, int argPropertySize)

The operation functionality is the same as the matching Blocking API operation. See the “loginCable” section on page 3-13 for more information.

logoutCableThe following section provides information about the logoutCable operation syntax.

Syntax

The logoutCable syntax is as follows:

int logoutCable(char* argCpe, char* argCm, char* argIp, char* argDomain)


OL-31824-01

Chapter 4 Nonblocking API C++ setLogger Method

The operation functionality is the same as the matching Blocking API operation. See the “logoutCable” section on page 3-15 for more information.

C++ setLogger MethodThe following section provides information about the C++ setLogger method operation syntax.

Syntax

The C++ setLogger Method syntax is as follows:

void setLogger(Logger *argLogger)

The operation functionality is the same as the matching Blocking API operation. See the “C++ setLogger Method” section on page 3-35 for more information.

C++ init MethodThe following section provides information about the C++ init method operation syntax.

Syntax

The C++ init Method syntax is as follows:

Bool init(int argThreadPriority = 0, Uint32 argBufferSize = DEFAULT_BUFFER_SIZE, Uint32 argKeepAliveDuration = DEFAULT_KEEP_ALIVE_DURATION, Uint32 argConnectionTimeout= DEFAULT_CONNECTION_TIMEOUT, Uint32 argReconnectTimeout = NO_RECONNECT)

The operation functionality is the same as the matching Blocking API operation. See the “C++ init Method” section on page 3-36 for more information.

C SMNB_init FunctionThe following sections provide information about the C SMNB_init function operation:



Syntax

The C SMNB_init function syntax is as follows:

SMNB_HANDLE SMNB_init(int argThreadPriority, Uint32 argBufferSize, Uint32 argKeepAliveDuration, Uint32 argConnectionTimeout)

The operation functionality is the same as the matching Blocking API operation. See the “C SMB_init Function” section on page 3-37 for more information.


OL-31824-01

Chapter 4 Nonblocking API C SMNB_release Function

Return Value

The return value is a SMNB_HANDLE handle to the API. A NULL handle means, the initialization has failed.

C SMNB_release FunctionThe following section provides information about the C SMNB_release function syntax.

Syntax

The C SMNB_release function syntax is as follows:

void SMNB_release(SMNB_HANDLE argApiHandle)

The operation functionality is the same as the matching Blocking API operation. See the “C SMB_release Function” section on page 3-38 for more information.

setReconnectTimeoutThe following section provides information about the setReconnectTimeout operation syntax.

Syntax

The setReconnectTimeout syntax is as follows:

void setReconnectTimeout(Uint32 reconnectTimeout)

The operation functionality is the same as the matching Blocking API operation. See the “setReconnectTimeout” section on page 3-38 for more information.

setNameThe following section provides information about the setName operation syntax.

Syntax

The setName syntax is as follows:

void setName(char *argName)

The operation functionality is the same as the matching Blocking API operation. See the “setName” section on page 3-39 for more information.

connectThe following section provides information about the connect operation syntax.


OL-31824-01

Chapter 4 Nonblocking API disconnect

Syntax

The connect syntax is as follows:

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

The operation functionality is the same as the matching Blocking API operation. See the “connect” section on page 3-40 for more information.

disconnectThe following section provides information about the disconnect operation syntax.

Syntax

The disconnect syntax is as follows:

bool disconnect()

The operation functionality is the same as the matching Blocking API operation. See the “disconnect” section on page 3-40 for more information.

isConnectedThe following section provides information about the isConnected operation syntax.

Syntax

The isConnected syntax is as follows:

bool isConnected()

The operation functionality is the same as the matching Blocking API operation. See the “isConnected” section on page 3-41 for more information.

Nonblocking API C++ Code ExamplesThis section provides a code example for logging in and logging out subscribers.

Login and LogoutThe following example logs in a predefined number of subscribers to the Cisco Service Control Subscriber Manager and then logs them out. Note the implementation of a disconnect listener and a result handler.

#include "SmApiNonBlocking.h"#include <stdio.h>

void connectionIsDown(){ printf("disconnect listener callback:: connection is down\n");


OL-31824-01

Chapter 4 Nonblocking API Login and Logout

}

int count = 0;

//prints every error that occursvoid handleError(Uint32 argHandle, ReturnCode* argReturnCode){ ++count; printf("\terror %d:\n",count); printReturnCode(argReturnCode); freeReturnCode(argReturnCode);}

//prints a success result every 100 resultsvoid handleSuccess(Uint32 argHandle, ReturnCode* argReturnCode){ if (++count%100 == 0) { printf("\tresult %d:\n",count); printReturnCode(argReturnCode); } freeReturnCode(argReturnCode);}

//waits for result number 'last result' to arrivevoid waitForLastResult(int lastResult){ while (count<lastResult) { ::Sleep(100); }}

void checkTheArguments(int argc, char* argv[]){ if (argc != 4) { printf("usage: LoginLogout <SM-address> <domain> <num-susbcribers>"); exit(1); }}

void main (int argc, char* argv[]){ //check arguments checkTheArguments(argc, argv); int numSubscribersToLogin = atoi(argv[3]);

//instantiation SmApiNonBlocking nbapi; //initiation nbapi.init(); nbapi.setDisconnectListener(connectionIsDown); nbapi.connect(argv[1]); nbapi.setReplyFailCallBack(handleError); nbapi.setReplySuccessCallBack(handleSuccess); //login char name[10]; char ipString[15]; char* ip = &(ipString[0]); MappingType type = IP_RANGE; Uint32 ipVal = 0x0a000000;

printf("login of %d subscribers\n",numSubscribersToLogin);


OL-31824-01


for (int i=0; i<numSubscribersToLogin; i++) { sprintf((char*)name,"s%d",i); sprintf((char*)ip,"%d.%d.%d.%d", (int)((ipVal & 0xFF000000) >> 24), (int)((ipVal & 0x00FF0000) >> 16), (int)((ipVal & 0x0000FF00) >> 8), (int)(ipVal & 0x000000FF)); ipVal++;

nbapi.login(name, //subscriber name &ip, //a single ip mapping &type, 1, NULL, //no properties NULL, 0, argv[2], //domain false, //mappings are not additive -1); //disable auto-logout } waitForLastResult(numSubscribersToLogin); //logout printf("logout of %d subscribers",numSubscribersToLogin); ipVal = 0x0a000000; for (i=0; i<numSubscribersToLogin; i++) { sprintf((char*)ip,"%d.%d.%d.%d", (int)((ipVal & 0xFF000000) >> 24), (int)((ipVal & 0x00FF0000) >> 16), (int)((ipVal & 0x0000FF00) >> 8), (int)(ipVal & 0x000000FF)); ipVal++;

nbapi.logoutByMapping(ip, type, argv[2]); } waitForLastResult(numSubscribersToLogin*2); nbapi.disconnect();}

The following example logs in a predefined number of IPv6 subscribers to the Cisco Service Control Subscriber Manager and then logs them out. Note the implementation of a disconnect listener and a result handler.

#include "SmApiNonBlocking.h"#include <stdio.h>#include <stdlib.h>#include <sys/time.h>#include <time.h>#include <unistd.h>char api[30];void checkArguments(int argc, char* argv[]){ if (argc != 5) { printf("usage: api_method_fun <SM-address> <subscriber-name> " "<NoOfSubs> <domain>\n"); exit(1); }}void connectionIsDown(){


OL-31824-01


printf("disconnect listener callback:: connection is down\n");}int count = 0;void handleError(Uint32 argHandle, ReturnCode* argReturnCode){ ++count; printf("\tFAIL in %s %d:\n",api,count); printReturnCode(argReturnCode); freeReturnCode(argReturnCode);}void handleSuccess(Uint32 argHandle, ReturnCode* argReturnCode){

++count; { printf("\tPASS %s %d:\n",api,count); printReturnCode(argReturnCode); } freeReturnCode(argReturnCode);}int __nsleep(const struct timespec *req, struct timespec *rem){ struct timespec temp_rem;

if(nanosleep(req,rem)==-1) __nsleep(rem,&temp_rem); else return 1;}

int msleep(unsigned long milisec){ struct timespec req={0},rem={0}; time_t sec=(int)(milisec/1000); milisec=milisec-(sec*1000); req.tv_sec=sec; req.tv_nsec=milisec*1000000L; __nsleep(&req,&rem);

return 1;}void waitForLastResult(int lastResult){ while ((count < lastResult) ) { msleep(50); printf ("waiting %d:",count); }}

int main(int argc, char* argv[]){

checkArguments(argc,argv);SmApiNonBlocking nbapi;//initiationif (!nbapi.init()) { printf ("Problem in NB API init()\n"); exit(0); }nbapi.setDisconnectListener(connectionIsDown);

if (nbapi.connect(argv[1])) // connect to the SM printf ("NB API is connected to SM\n");else


OL-31824-01


{ printf ("NB API is not connected to SM\n"); exit(0);

}

nbapi.setReplyFailCallBack(handleError); nbapi.setReplySuccessCallBack(handleSuccess);

MappingType type = TYPE_IPV6; char * propKeys[] = {"packageId","monitor","upVlinkId","downVlinkId"}; char * propValues[] = {"88","7","999","666"};

char* customKey = "custom-key";char* customVal = "10";

int noOfSub=atoi(argv[3]);sprintf (api,"Login New:");//Login IPV6 subscribers with mappingfor (int i=0;i<noOfSub;i++)

{ char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%dnew",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0]; printf ("Name:%s IP:%s \n",subname,subip); nbapi.login(

subname,//argv[2], // name &ip,//&(argv[3]), // mapping &type, // mapping type

1,propKeys, // property key

propValues, // property value 4, // number of properties argv[4],

false,-1);

}waitForLastResult(noOfSub);

//LogoutByNamesprintf (api,"LogoutByName():");

count=0; for (int i=0;i<noOfSub;i++) { char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%dnew",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0]; printf ("Name:%s IP:%s \n",subname,subip);

nbapi.logoutByName( subname,//argv[2], // name &ip,//&(argv[3]), // mapping &type, // mapping type 1);

} waitForLastResult(noOfSub);

//LogoutByNameFromDomain count=0; for (int i=0;i<noOfSub;i++)


OL-31824-01


{ char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%dnew",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0]; printf ("Name:%s IP:%s \n",subname,subip);

nbapi.login( subname,//argv[2], // name &ip,//&(argv[3]), // mapping &type, // mapping type 1, propKeys, // property key propValues, // property value 4, // number of properties argv[4], false, -1);


sprintf (api,"LogoutByNameFromDomain:"); count=0;

for (int i=0;i<noOfSub;i++) { char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%dnew",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0]; printf ("Name:%s IP:%s \n",subname,subip);

nbapi.logoutByNameFromDomain( subname,//argv[2], // name &ip,//&(argv[3]), // mapping &type, // mapping type 1,argv[4]);


//LogoutByMapping count=0; for (int i=0;i<noOfSub;i++) { char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%dnew",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0]; printf ("Name:%s IP:%s \n",subname,subip);

nbapi.login( subname,//argv[2], // name &ip,//&(argv[3]), // mapping &type, // mapping type 1, propKeys, // property key propValues, // property value 4, // number of properties argv[4],


OL-31824-01

Chapter 4 Nonblocking API Nonblocking API C Code Examples

false, -1);


sprintf (api,"LogoutByMapping()"); count=0; for (int i=0;i<noOfSub;i++) { char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%dnew",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0]; printf ("Name:%s IP:%s \n",subname,subip);

nbapi.logoutByMapping( ip,//&(argv[3]), // mapping type, // mapping type argv[4]);


if (nbapi.isConnected())printf ("\nNB API Connected\n");

elseprintf ("\nNB API Not Connected\n");

nbapi.disconnect(); if (nbapi.isConnected()) printf ("\nNB API Connected\n"); else printf ("\nNB API Not Connected\n");

return 0;}

Nonblocking API C Code ExamplesThis section provides a code example for logging in and logging out subscribers.

Login and LogoutThe following example logs in a predefined number of subscribers to the Cisco Service Control Subscriber Manager and then logs them out. Note the implementation of a disconnect listener and a result handler.

#include "SmApiNonBlocking_c.h"#include <stdio.h>

void connectionIsDown(){ printf("disconnect listener callback:: connection is down\n");}


OL-31824-01


int count = 0;

//prints every error that occursvoid handleError(Uint32 argHandle, ReturnCode* argReturnCode){ ++count; printf("\terror %d:\n",count); printReturnCode(argReturnCode); freeReturnCode(argReturnCode);}

//prints a success result every 100 resultsvoid handleSuccess(Uint32 argHandle, ReturnCode* argReturnCode){ if (++count%100 == 0) { printf("\tresult %d:\n",count); printReturnCode(argReturnCode); } freeReturnCode(argReturnCode);}

//waits for result number 'last result' to arrivevoid waitForLastResult(int lastResult){ while (count<lastResult) { ::Sleep(100); }}

void checkTheArguments(int argc, char* argv[]){ if (argc != 3) { printf("usage: LoginLogout <SM-address> <domain> <num-susbcribers>"); exit(1); }}

void main (int argc, char* argv[]){ //check arguments checkTheArguments(argc, argv); int numSubscribersToLogin = atoi(argv[3]);

//instantiation SMNB_HANDLE nbapi = SMNB_init(0,2000000,10,30); if (nbapi == NULL) { exit(1); }

SMNB_setDisconnectListener(nbapi,connectionIsDown); SMNB_connect(nbapi,argv[1],14374); SMNB_setReplyFailCallBack(nbapi,handleError); SMNB_setReplySuccessCallBack(nbapi,handleSuccess); //login char name[10]; char ipString[15]; char* ip = &(ipString[0]); MappingType type = IP_RANGE; Uint32 ipVal = 0x0a000000;


OL-31824-01


printf("login of %d subscribers\n",numSubscribersToLogin); for (int i=0; i<numSubscribersToLogin; i++) { sprintf((char*)name,"s%d",i); sprintf((char*)ip,"%d.%d.%d.%d", (int)((ipVal & 0xFF000000) >> 24), (int)((ipVal & 0x00FF0000) >> 16), (int)((ipVal & 0x0000FF00) >> 8), (int)(ipVal & 0x000000FF)); ipVal++;

SMNB_login(nbapi, name, //subscriber name &ip, //a single ip mapping &type, 1, NULL, //no properties NULL, 0, argv[2], //domain false, //mappings are not additive -1); //disable auto-logout } waitForLastResult(numSubscribersToLogin); //logout printf("logout of %d subscribers",numSubscribersToLogin); ipVal = 0x0a000000; for (i=0; i<numSubscribersToLogin; i++) { sprintf((char*)ip,"%d.%d.%d.%d", (int)((ipVal & 0xFF000000) >> 24), (int)((ipVal & 0x00FF0000) >> 16), (int)((ipVal & 0x0000FF00) >> 8), (int)(ipVal & 0x000000FF)); ipVal++;

SMNB_logoutByMapping(nbapi, ip, type, argv[1]); } waitForLastResult(numSubscribersToLogin*2); SMNB_disconnect(nbapi); SMNB_release(nbapi);}

The following example logs in a predefined number of IPv6 subscribers to the Cisco Service Control Subscriber Manager and then logs them out. Note the implementation of a disconnect listener and a result handler.

#include "SmApiNonBlocking_c.h"#include <stdio.h>#include <stdlib.h>#include <sys/time.h>#include <time.h>#include <unistd.h>char api[30];int count = 0;void checkArguments(int argc, char* argv[]){ if (argc != 5) { printf("usage: api_method_fun <SM-address> <subscriber-name> " "<NoOfSubs> <domain>\n");


OL-31824-01


exit(1); }}

void connectionIsDown(){ printf("disconnect listener callback:: connection is down\n");}

void handleError(Uint32 argHandle, ReturnCode* argReturnCode){ ++count; printf("\nerror in %s %d:\n",api,count); printReturnCode(argReturnCode); freeReturnCode(argReturnCode);}

void handleSuccess(Uint32 argHandle, ReturnCode* argReturnCode){

++count; printf("\nPASS %s %d:\n",api,count); freeReturnCode(argReturnCode);}

int __nsleep(const struct timespec *req, struct timespec *rem){ struct timespec temp_rem;

if(nanosleep(req,rem)==-1) __nsleep(rem,&temp_rem); else return 1;}

int msleep(unsigned long milisec){ struct timespec req={0},rem={0}; time_t sec=(int)(milisec/1000); milisec=milisec-(sec*1000); req.tv_sec=sec; req.tv_nsec=milisec*1000000L; __nsleep(&req,&rem);

return 1;}void waitForLastResult(int lastResult){ while ((count < lastResult) ) { msleep(50); printf ("waiting %d:",count); }}

int main(int argc, char* argv[]){

checkArguments(argc,argv);SMNB_HANDLE nbapi = SMNB_init(0,2000000,10,30);if (nbapi == NULL)


OL-31824-01


{printf ("Non Blocking Init Failed\n");exit(1);}SMNB_setDisconnectListener(nbapi,connectionIsDown);SMNB_connect(nbapi,argv[1],14374);SMNB_setReplyFailCallBack(nbapi,handleError);SMNB_setReplySuccessCallBack(nbapi,handleSuccess);

MappingType type = TYPE_IPV6;

char * propKeys[] = {"packageId","monitor","upVlinkId","downVlinkId"}; char * propValues[] = {"1","1","100","101"};

char* customKey = "custom-key";char* customVal = "10";

int noOfSub=atoi(argv[3]);sprintf (api,"Login New:");for (int i=0;i<noOfSub;i++)

{ char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%d",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0]; SMNB_login(nbapi,

subname, // name &ip, // mapping &type, // mapping type

1,propKeys, // property key

propValues, // property value 4, // number of properties argv[4],

false,-1);

}waitForLastResult(noOfSub);

sprintf (api,"LogoutByName():"); count=0; for (int i=0;i<noOfSub;i++) { char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%d",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0];

SMNB_logoutByName(nbapi, subname, // name &ip, // mapping &type, // mapping type 1);


sprintf (api,"Re Login:"); count=0;

for (int i=0;i<noOfSub;i++) {


OL-31824-01


char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%d",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0];

SMNB_login(nbapi, subname, // name &ip, // mapping &type, // mapping type 1, propKeys, // property key propValues, // property value 4, // number of properties argv[4], false, -1);


sprintf (api,"LogoutByNameFromDomain:");count=0;

for (int i=0;i<noOfSub;i++) { char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%d",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0];

SMNB_logoutByNameFromDomain(nbapi, subname,//argv[2], // name &ip,//&(argv[3]), // mapping &type, // mapping type 1,argv[4]);


count=0;sprintf (api,"Re Login");for (int i=0;i<noOfSub;i++)

{ char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%d",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0];

SMNB_login(nbapi, subname, // name &ip, // mapping &type, // mapping type 1, propKeys, // property key propValues, // property value 4, // number of properties argv[4], false, -1);



OL-31824-01


sprintf (api,"LogoutByMapping()"); count=0; for (int i=0;i<noOfSub;i++) { char subname[2000]="",subip[50]="",*ip; sprintf (subname,"%s%d",argv[2],i); sprintf (subip,"abcd:%d:%d:%d::/64",((i / 256*256) % 256), ((i / 256) % 256),(i % 256)); ip=&subip[0];

SMNB_logoutByMapping(nbapi, ip,//&(argv[3]), // mapping type, // mapping type argv[4]);


SMNB_disconnect(nbapi);

return 0;}


OL-31824-01

Cisco Service Control SubscOL-31824-01

A

P P E N D I X A
List of Error Codes

IntroductionThis appendix provides a list of error codes that are used in the C API and C++ API.

List of Error Codes Error codes are used to interpret the actual error for which a ReturnCode (holding an ErrorCode) was returned.

The error code enumeration is given in the GeneralDefs.h header file.

Table A-1 provides a list of the error codes and their descriptions.

Table A-1 List of Error Codes

Error Code Description

ERROR_CODE_ARRAY_ACCESS Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_ATTRIBUTE_NOT_FOUND Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_BAD_SUBSCRIBER_MAPPING A mapping was formatted badly or assigned to the subscriber illegally.

ERROR_CODE_BAD_VPN_MAPPING A mapping was formatted badly or assigned illegally to the VPN.

ERROR_CODE_CLASS_CAST Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_CLASS_NOT_FOUND Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_CLIENT_INTERNAL_ERROR Internal error.

ERROR_CODE_CLIENT_OPERATION_TIMEOUT Blocking API operation result did not return until the reply timeout expired.

ERROR_CODE_CLIENT_OUT_OF_THREADS Internal error.

A-1riber Manager C/C++ API Programmer Guide

Appendix A List of Error Codes List of Error Codes

ERROR_CODE_DATABASE_EXCEPTION Internal Cisco Service Control Subscriber Manager error.Database error occurred during the operation.

ERROR_CODE_DOMAIN_NOT_FOUND Domain provided to the operation does not exist in the Cisco Service Control Subscriber Manager domain repository.

ERROR_CODE_ILLEGAL_ARGUMENT One of the arguments provided to the method is illegal.

ERROR_CODE_ILLEGAL_STATE Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_ILLEGAL_SUBSCRIBER_NAME The subscriber name has more than 64 characters or any of these special characters, such as single or double quotes, or grave accent (`).

ERROR_CODE_INTERRUPTED_EXCEPTION Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_INVALID_ATTRIBUTE_VALUE Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_NOT_A_SUBSCRIBER_DOMAIN Domain provided to the operation exists in the Cisco Service Control Subscriber Manager domain repository, but is not a subscriber domain.

ERROR_CODE_NULL_POINTER Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_NUMBER_FORMAT A VLAN mapping string provided to the API does not represent a decimal number.

ERROR_CODE_OBJECT_NOT_FOUND Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_OPERATION_NOT_FOUND Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_OUT_OF_MEMORY Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_RUNTIME Internal Cisco Service Control Subscriber Manager error.

ERROR_CODE_SE_ERROR Internal Cisco Service Control Subscriber Manager error. The Cisco Service Control Subscriber Manager could not perform the operation on the Cisco SCE device.

ERROR_CODE_SUBSCRIBER_DOES_NOT_EXIST The subscriber on which the operation is performed does not exist in the Cisco Service Control Subscriber Manager database.

ERROR_CODE_SUBSCRIBER_DOMAIN_ASSOCIATION The subscriber exists in the Cisco Service Control Subscriber Manager database but is associated with a domain other than the one specified by the operation.

Table A-1 List of Error Codes (continued)


A-2Cisco Service Control Subscriber Manager C/C++ API Programmer Guide

OL-31824-01


ERROR_CODE_SUBSCRIBER_MAPPING_CONGESTION The mappings provided for the subscriber by the operation already belong to another subscriber.

ERROR_CODE_SUSBSCRIBER_ALREADY_EXISTS The subscriber on which the operation was performed already exists in the Cisco Service Control Subscriber Manager database.

ERROR_CODE_UNKNOWN Internal Cisco Service Control Subscriber Manager error or an API error.

ERROR_CODE_VALUE_DOES_NOT_MEET_CONSTRAINTS One of the properties provided to the method is illegal. For more information about subscriber properties, see the “Subscriber Properties” section on page 2-10.

ERROR_CODE_VPN_ALREADY_EXISTS The VPN on which the operation was performed already exists in the Cisco Service Control Subscriber Manager database.

ERROR_CODE_VPN_DOES_NOT_EXIST The VPN on which the operation was performed does not exist in the Cisco Service Control Subscriber Manager database.

Table A-1 List of Error Codes (continued)



OL-31824-01



OL-31824-01

Cisco Service Control Subscriber Manager C/C++ API ... · 3 Cisco Service Control Subscriber...

Documents

Transcript of Cisco Service Control Subscriber Manager C/C++ API ... · 3 Cisco Service Control Subscriber...