TSP: The Transport Sample Protocol



Consumer Core Library
[TSP Core Libraries]

Collaboration diagram for Consumer Core Library:The Consumer module is the set of all consumer library interface. More...


Modules

 RPC Client
 The TSP_RPCClientLib module is the set of functions which encapsulate the RPC machinery.
 XML-RPC Client
 The Client module is the set of functions which encapsulate the RPC machinery.

Data Structures

struct  TSP_sample
 Structure used to get a TSP sample symbol. More...

Defines

#define TSP_URL_FORMAT_USAGE   "\TSP URL format is defined by <PROTOCOL://HOST/SERVER:PORT> \n\\tPROTOCOL if omitted, is defaulted to 'rpc' \n\\tHOST if omitted, is defaulted to 'localhost' \n\\tSERVER if omitted, find any TSP server name \n\\tPORT if omitted, find first TSP server number \n\\tSimplified possible syntaxes : \n\\t\tPROTOCOL://HOST/SERVER = PROTOCOL://HOST/SERVER:(find first) \n\\t\tPROTOCOL://HOST/:0 = PROTOCOL://HOST/(find any):0 \n\\t\tPROTOCOL://HOST = PROTOCOL://HOST/(find any):(find first) \n\\t\tPROTOCOL:// or PROTOCOL = PROTOCOL://localhost/(find any):(find first)\n\\t\tvoid, /, //, /// or :/// = rpc://localhost/(find any):(find first) \n\\tOthers may have unpredictable results .. \n"
 Connects to a provider based on a given URL.

Typedefs

typedef void * TSP_provider_t
 Opaque handle type for provider.
typedef void(*) TSP_sample_callback_t (TSP_sample_t *sample, void *user_data)
 Callback function type used to receive a sample item.
typedef TSP_sample TSP_sample_t
 Structure used to get a TSP sample symbol.

Functions

void TSP_consumer_connect_all (const char *host_name, TSP_provider_t **providers, int *nb_providers)
 Connects to all found providers on the given host.
void TSP_consumer_disconnect_all (TSP_provider_t providers[])
 Disconnected all found providers.
_EXPORT_TSP_CONSUMER void TSP_consumer_disconnect_one (TSP_provider_t provider)
 Disconnect one given provider.
_EXPORT_TSP_CONSUMER void TSP_consumer_end ()
 End of TSP library use call this function when you are done with the librairy.
_EXPORT_TSP_CONSUMER uint32_t TSP_consumer_get_channel_id (TSP_provider_t provider)
 Return the TSP channel Id associated with this TSP session if a TSP Request Open has already been sent to this provider.
_EXPORT_TSP_CONSUMER const
char * 
TSP_consumer_get_connected_name (TSP_provider_t provider)
 Request provider name.
_EXPORT_TSP_CONSUMER const
TSP_sample_symbol_extended_info_list_t
TSP_consumer_get_extended_information (TSP_provider_t provider)
 Retrieve the provider extended information list.
_EXPORT_TSP_CONSUMER const
TSP_answer_sample_t
TSP_consumer_get_information (TSP_provider_t provider)
 Retrieve the provider list.
const TSP_sample_symbol_info_list_tTSP_consumer_get_requested_sample (TSP_provider_t provider)
 Retrieve the symbols requested list.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_init (int *argc, char **argv[])
 Initialisation for TSP library.
void TSP_consumer_print_invalid_symbols (FILE *fs, TSP_sample_symbol_info_list_t *symbols, const char *tsp_provider_url)
 Print the symbols flagged as invalid in the provided sample symbol info list.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_read_sample (TSP_provider_t provider, TSP_sample_t *sample, int *new_sample)
 Read a sample symbol.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_async_sample_read (TSP_provider_t provider, TSP_consumer_async_sample_t *async_sample_read)
 Send a TSP asynchronous sample read request.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_async_sample_write (TSP_provider_t provider, TSP_consumer_async_sample_t *async_sample_write)
 Send a TSP asynchronous sample write request.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_close (TSP_provider_t provider)
 Close the session.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_extended_information (TSP_provider_t provider, int32_t *pgis, int32_t pgis_len)
 Request provider extended information.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_filtered_information (TSP_provider_t provider, int filter_kind, char *filter_string)
 Request provider information.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_information (TSP_provider_t provider)
 Request provider information.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_open (TSP_provider_t provider, int custom_argc, char *custom_argv[])
 Ask the provider for a new consumer session.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_sample (TSP_provider_t provider, TSP_sample_symbol_info_list_t *symbols)
 Ask the provider for a list of symbols.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_sample_destroy (TSP_provider_t provider)
 Stop and destroy the sampling sequence.
_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_sample_init (TSP_provider_t provider, TSP_sample_callback_t callback, void *user_data)
 Prepare and start the sampling sequence.
double TSP_sample2double (TSP_sample_t sample)
 Convert a sample value to double.


Detailed Description

The Consumer module is the set of all consumer library interface.


Define Documentation

#define TSP_URL_FORMAT_USAGE   "\TSP URL format is defined by <PROTOCOL://HOST/SERVER:PORT> \n\\tPROTOCOL if omitted, is defaulted to 'rpc' \n\\tHOST if omitted, is defaulted to 'localhost' \n\\tSERVER if omitted, find any TSP server name \n\\tPORT if omitted, find first TSP server number \n\\tSimplified possible syntaxes : \n\\t\tPROTOCOL://HOST/SERVER = PROTOCOL://HOST/SERVER:(find first) \n\\t\tPROTOCOL://HOST/:0 = PROTOCOL://HOST/(find any):0 \n\\t\tPROTOCOL://HOST = PROTOCOL://HOST/(find any):(find first) \n\\t\tPROTOCOL:// or PROTOCOL = PROTOCOL://localhost/(find any):(find first)\n\\t\tvoid, /, //, /// or :/// = rpc://localhost/(find any):(find first) \n\\tOthers may have unpredictable results .. \n"

Connects to a provider based on a given URL.

Parameters:
url URL to the provider that must be opened Possible formats for URL are defined in following macro


Typedef Documentation

typedef void* TSP_provider_t

Opaque handle type for provider.

typedef void(*) TSP_sample_callback_t(TSP_sample_t *sample, void *user_data)

Callback function type used to receive a sample item.

FIXME : The callback function should transmit the error code too ( ex : typedef void (*TSP_sample_callback_t) (TSP_sample_t* sample, TSP_consumer_status_t status);

typedef struct TSP_sample TSP_sample_t

Structure used to get a TSP sample symbol.

A variable sample of this type is filled by a call to TSP_consumer_read_sample.


Function Documentation

void TSP_consumer_connect_all ( const char *  host_name,
TSP_provider_t **  providers,
int *  nb_providers 
)

Connects to all found providers on the given host.

The consumer may use the TSP_consumer_get_connected_name to retreive information about each provider, so as to choose what provider(s) will be left opened.

Parameters:
host_name Name of host on which the providers must be opened
providers Array of found providers
nb_providers Total number of providers in 'providers' array

void TSP_consumer_disconnect_all ( TSP_provider_t  providers[]  ) 

Disconnected all found providers.

Parameters:
providers Array of providers from which we want to be disconnected

_EXPORT_TSP_CONSUMER void TSP_consumer_disconnect_one ( TSP_provider_t  provider  ) 

Disconnect one given provider.

Parameters:
provider IN, the provider to be disconnected from.

_EXPORT_TSP_CONSUMER void TSP_consumer_end (  ) 

End of TSP library use call this function when you are done with the librairy.

This function must be called once.

_EXPORT_TSP_CONSUMER uint32_t TSP_consumer_get_channel_id ( TSP_provider_t  provider  ) 

Return the TSP channel Id associated with this TSP session if a TSP Request Open has already been sent to this provider.

Parameters:
provider the TSP session to provider
Returns:
the channel Id if the session is open -1 if session not opened.

_EXPORT_TSP_CONSUMER const char* TSP_consumer_get_connected_name ( TSP_provider_t  provider  ) 

Request provider name.

This string should provide some information for a given provider. See it as a naming service.

Parameters:
provider The provider handle
Returns:
The provider name

_EXPORT_TSP_CONSUMER const TSP_sample_symbol_extended_info_list_t* TSP_consumer_get_extended_information ( TSP_provider_t  provider  ) 

Retrieve the provider extended information list.

Get the provider information asked by TSP_consumer_request_information This function may be called multiple times per session

Parameters:
provider The provider handle
Returns:
the provider extended information structure

_EXPORT_TSP_CONSUMER const TSP_answer_sample_t* TSP_consumer_get_information ( TSP_provider_t  provider  ) 

Retrieve the provider list.

Get the provider information asked by TSP_consumer_request_information This function may be called multiple times per session

Parameters:
provider The provider handle
Returns:
the provider information structure

const TSP_sample_symbol_info_list_t* TSP_consumer_get_requested_sample ( TSP_provider_t  provider  ) 

Retrieve the symbols requested list.

The function TSP_consumer_request_sample must be called first. This function may be called multiple times per session.

Parameters:
provider The provider handle
Returns:
the requested symbols list.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_init ( int *  argc,
char **  argv[] 
)

Initialisation for TSP library.

Call this function before using main(argc, argv) function arguments. This function removes the arguments it knows from the argument list, leaving anything it does not recognize for your application to parse or ignore. This creates a set of standard arguments accepted by all TSP applications. This function must be called once.

Parameters:
argc Use the argc main arg before using it
argv Use the argv main arg before using it
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error.

void TSP_consumer_print_invalid_symbols ( FILE *  fs,
TSP_sample_symbol_info_list_t symbols,
const char *  tsp_provider_url 
)

Print the symbols flagged as invalid in the provided sample symbol info list.

Parameters:
[in] fs the STDIO file stream
[in] symbols the list of symbol to analyse
[in] tsp_provider_url the provider TSP URL.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_read_sample ( TSP_provider_t  provider,
TSP_sample_t sample,
int *  new_sample 
)

Read a sample symbol.

Parameters:
provider The provider handle
sample The returned symbol if there is one
new_sample When TRUE, there is a new sample, else the sample value is meaningless
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error.
Todo:
  • Some kind of get_last_error func must be implemented to read the error codes (EOF, RECONF ... ).
  • When the other types will be implemented (RAW, STRING) the TSP_sample_t type will not work anymore as it is double specific for now.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_async_sample_read ( TSP_provider_t  provider,
TSP_consumer_async_sample_t *  async_sample_read 
)

Send a TSP asynchronous sample read request.

Parameters:
[in] provider the TSP session onto we want to send the request
[in,out] async_sample_read the async read message itself on entry describes the symbol to read on return contains the read value (if success)
Returns:
TSP_STATUS_OK on success other TSP_STATUS_ERROR on failure.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_async_sample_write ( TSP_provider_t  provider,
TSP_consumer_async_sample_t *  async_sample_write 
)

Send a TSP asynchronous sample write request.

Parameters:
[in] provider the TSP session onto we want to send the request
[in] async_sample_write the async write message itself
Returns:
TSP_STATUS_OK on success other TSP_STATUS_ERROR on failure.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_close ( TSP_provider_t  provider  ) 

Close the session.

Parameters:
provider The provider handle
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_extended_information ( TSP_provider_t  provider,
int32_t *  pgis,
int32_t  pgis_len 
)

Request provider extended information.

Ask the provider for extended informations for the specified PGI. This function should be called multiple times only to refresh the structure returned by the TSP_consumer_get_extended_information function.

Parameters:
[in] provider The provider handle
[in] pgis the list of PGI for which we want extended informations
[in] pgis_len the length of the pgis array
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_filtered_information ( TSP_provider_t  provider,
int  filter_kind,
char *  filter_string 
)

Request provider information.

Ask the provider informations about several parameters, including the available symbol list that can be asked. This function should be called multiple times only to refresh the structure returned by the TSP_consumer_get_information function.

Parameters:
provider The provider handle
filter_kind the kind of filter
filter_string the filter string
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_information ( TSP_provider_t  provider  ) 

Request provider information.

Ask the provider informations about several parameters, including the available symbol list that can be asked. This function should be called multiple times only to refresh the structure returned by the TSP_consumer_get_information function.

Parameters:
provider The provider handle
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_open ( TSP_provider_t  provider,
int  custom_argc,
char *  custom_argv[] 
)

Ask the provider for a new consumer session.

This function must be called and must succeed for the program to be able to call other TSP_REQUEST_* functions.

Parameters:
provider The provider handle
custom_argc Custom provider data stream initialisation (optional : set 0)
custom_argv Custom provider data stream initialisation (optional : set 0)
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error. custom_argc and custom_argv works like main argc and argv :
  • custom_argv[0] is ignored but a real string must be provided (any string will do, but there MUST be a string, even an empty string )
  • custom_argc is the total number of elements in custom_argv (included custom_argc[0])
  • if you do not want to provide custom data stream initialisation, call the function with custom_argc=custom_argv=0 ( as a consequency if a stream is provided on the consumer command line, it will be used ) If you provide your own custom_argc and custom_argv and the user provided data stream initialisation arguments on the provider command line, the user command line will be ignored and your arguments call will be used
  • If you call the function with custom_argc=1 (with any string in custom_argv[0]) this means "overide consumer command line data stream initialisation, and set 0 parameters". It means that the provided data stream initialisation will be done with 0 parameters. It is a way to prevent the user from providing initialisation parameters thrue the command line.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_sample ( TSP_provider_t  provider,
TSP_sample_symbol_info_list_t symbols 
)

Ask the provider for a list of symbols.

When the list of available symbols was retreived via TSP_consumer_request_information, and TSP_consumer_get_information, the consumer may choose some symbols, set their phase and period and call this function to prepare the provider to sample these symbols. The symbol is retrieved by name. The 'index' member of the symbols->val structure is not used (to retreive the provider global index of a symbol uses the TSP_consumer_get_requested_sample function after this function call). This function should be called multiple times only to refresh the structure returned by the TSP_consumer_get_requested_sample function.

Parameters:
provider The provider handle
symbols The request symbols list
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_sample_destroy ( TSP_provider_t  provider  ) 

Stop and destroy the sampling sequence.

Parameters:
provider The provider handle
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error.

_EXPORT_TSP_CONSUMER int32_t TSP_consumer_request_sample_init ( TSP_provider_t  provider,
TSP_sample_callback_t  callback,
void *  user_data 
)

Prepare and start the sampling sequence.

Parameters:
provider The provider handle
callback Address of a callback function that must be called
user_data pointer on any custom user data ( set 0 if not used) do not want to use any callback function, and use the TSP_consumer_read_sample function instead. DO NOT USE BOTH. Using the TSP_consumer_read_sample function is easier as you do not have to deal with multi-thread problems, but the callback function is CPU friendlier (theoricaly at least...)
Returns:
TSP_STATUS_OK on success TSP_STATUS_ERROR_xxx on error.

double TSP_sample2double ( TSP_sample_t  sample  ) 

Convert a sample value to double.

This is a convenient for easy simple double type to multi-type transition. Numeric sample value a translated to numeric double values whereas char, uchar and raw are translated to 0.

Parameters:
sample the sample to convert
Returns:
the double value of the sample

Framework Home Page.


Beware !! TSP wave is coming...