Non-blocking API

This module describes the features and operations of the Non-blocking API and provides code examples.

This module introduces the Result Handler Callbacks, a feature unique to the Non-blocking API.

Multi-threading Support

The Non-blocking API supports an unlimited number of threads calling its methods simultaneously.

Note In a multi-threaded scenario for the Non-blocking API, the order of invocation is guaranteed : the API performs operations in the same chronological order that they were called.

Information About Result Handler Callbacks

The Non-blocking API enables the setting of result handler callbacks. The result handler callbacks are two functions for handleSuccess and handleError , as outlined in the following code.

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

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

•

Handle —Each API operation's return-value is a handle of type Uint32. This handle enables correlation between operation calls and their results. When a handle... operation is called with a handle of value X , the result will match 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 Example

The following example is a simple implementation of a result handler that counts the number of success/failure operations. This main method initiates the API and assigns a result handler.

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

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

Information About Non-blocking API Methods

Some of the methods return a non-negative int handle that may be used to correlate operation calls and their results (see Information About Result Handler Callbacks ). 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, except that: return values of Void are translated to NULL.

Note The error/fail callback will be 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 SM database state at the time of the call.

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

Syntax

The operation functionality is the same as the matching Blocking API operation. See the login operation for more information.

logoutByName

Syntax

The operation functionality is the same as the matching Blocking API operation. See the logoutByName operation for more information.

logoutByNameFromDomain

Syntax

The operation functionality is the same as the matching Blocking API operation. See the logoutByNameFromDomain operation for more information.

logoutByMapping

Syntax

The operation functionality is the same as the matching Blocking API operation. See the logoutByMapping operation for more information.

loginCable

Syntax

The operation functionality is the same as the matching Blocking API operation. See the loginCable loginCable operation in the Blocking API chapter for more information.

logoutCable

Syntax

The operation functionality is the same as the matching Blocking API operation. See the logoutCable operation for more information.

C++ setLogger Method

Syntax

The operation functionality is the same as the matching Blocking API operation. See the C++ setLogger Method operation for more information.

C++ init Method

Syntax

The operation functionality is the same as the matching Blocking API operation. See the C++ init Method operation for more information.

C SMNB_init Function

Syntax

The operation functionality is the same as the matching Blocking API operation. See the C SMB_init Function operation for more information.

Return Value

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

C SMNB_release Function

Syntax

The operation functionality is the same as the matching Blocking API operation. See the C SMB_release Function operation for more information.

setReconnectTimeout

Syntax

The operation functionality is the same as the matching Blocking API operation. See the setReconnectTimeout operation for more information.

setName

Syntax

The operation functionality is the same as the matching Blocking API operation. See the setName operation for more information.

connect

Syntax

The operation functionality is the same as the matching Blocking API operation. See the connect operation for more information.

disconnect

Syntax

The operation functionality is the same as the matching Blocking API operation. See the disconnect operation for more information.

isConnected

Syntax

The operation functionality is the same as the matching Blocking API operation. See the isConnected operation for more information.

Non-blocking API C++ Code Examples

This section provides a code example for logging in and logging out subscribers.

The following example logs in a predefined number of subscribers to the SM, 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"); 
} 
int count = 0; 
//prints every error that occurs 
void handleError(Uint32 argHandle, ReturnCode* argReturnCode) 
{ 
++count; 
printf("\terror %d:\n",count); 
printReturnCode(argReturnCode); 
freeReturnCode(argReturnCode); 
} 
//prints a success result every 100 results 
void 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 arrive 
void 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); 
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(); 
}

Non-blocking API C Code Examples

This section provides a code example for logging in and logging out subscribers.

The following example logs in a predefined number of subscribers to the SM, 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"); 
} 
int count = 0; 
//prints every error that occurs 
void handleError(Uint32 argHandle, ReturnCode* argReturnCode) 
{ 
++count; 
printf("\terror %d:\n",count); 
printReturnCode(argReturnCode); 
freeReturnCode(argReturnCode); 
} 
//prints a success result every 100 results 
void 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 arrive 
void 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; 
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); 
}

Table Of Contents

Non-blocking API

Multi-threading Support

Information About Result Handler Callbacks

Result Handler Callbacks Example

Information About Non-blocking API Methods

login

Syntax

logoutByName

Syntax

logoutByNameFromDomain

Syntax

logoutByMapping

Syntax

loginCable

Syntax

logoutCable

Syntax

C++ setLogger Method

Syntax

C++ init Method

Syntax

C SMNB_init Function

Syntax

Return Value

C SMNB_release Function

Syntax

setReconnectTimeout

Syntax

setName

Syntax

connect

Syntax

disconnect

Syntax

isConnected

Syntax

Non-blocking API C++ Code Examples

Login and Logout

Non-blocking API C Code Examples

Login and Logout