Prosody X cards and Prosody S virtual cards

Prosody X cards and Prosody S virtual cards are used by opening the card, and then using the tSMCardId value with the Prosody API to refer to that card. Normally, the card is opened using the acu_open_prosody() function, as documented in the resource management API guide. Internally, this will call the functions detailed in this section using the ACU_CARD_ID value as the tSMCardId value. Note that if acu_open_prosody() is used to open the card, acu_close_prosody() must be used to close the card.

The function to open a Prosody X card is sm_open_prosody_x() and the function to open a Prosody S (version 3) virtual card is sm_open_prosody_s_v3().

The programming interface

The declarations for this API are in apilib/prosody_x.h and applications using this API must be linked with the appropriate library - see Linking an application with the TiNG library

Note that global symbols named aculab_TiNG* may be defined by the API library. All such names are reserved for internal use in the API library code, and should not be used by applications.

Initialisation

From time to time new features are added to this API. This may require new fields to be added to structures. A mechanism is available to ensure that this does not cause any problems for code developed prior to the addition. This is achieved by defining all new fields such that the value zero selects backward compatible behaviour. To take advantage of this, structures should be cleared before use. For example,

	SM_OPEN_PROSODY_X_PARMS ap;
	memset(&ap, 0, sizeof(ap));
	strcpy(ap.px_locator, "10.1.2.3/mykey");
		... etc

This ensures that if a new field is ever added to this structure the new field is not left uninitialised.

Return values

The list of error codes that a function can return is only a list of typical errors. If a function is described as returning a standard error then it can return any such error. Also, when the description of a function says that it can return a particular error code (for example, ERR_SM_FIRMWARE_NOT_RUNNING), this does not mean that the function guarantees to detect this error condition in all circumstances. It merely means that if it does detect this error condition, then this is the code it will return.

There are situations where a successful call to a function causes an error condition to occur on a Prosody module, such as a request that requires a firmware module which has not been loaded. In these cases, the error condition is reported through a subsequent function call. This is usually a status function that is associated with the object which has caused the error. Some error conditions are more general. For example, a failure in communication with a Prosody module can be reported though any function call which refers to objects on that module.

Details of functions

API details by function

This is part of Prosody.