Prosody data communications

Ths Prosody data communications API consists of functions which cover the configuration and use of Prosody channels to send and receive arbitrary data.

The programming interface

The generic declarations for this API are in apilib/smdc.h. Each protocol and encoding has any additional declarations in a separate file (also in the apilib directory, all with names in the form smdc_*.h). Applications using this library must be linked with the appropriate object file, which is

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_CHANNEL_CHANNEL_CONFIG_PARMS ap;
	memset(&ap, 0, sizeof(ap));
	ap.chanel = chan;
		... 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.

Details of functions

The range of data communications facilities is summarised in the document Prosody Data Communcations Protocols and Encodings. This document also provides for each protocol details of any differences in behaviour of each API function compared to the general decription in API details by function.

This API is part of Prosody.