TSP: The Transport Sample Protocol



Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Consumer
[Core]


Modules

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


Data Structures

struct  TSP_consumer_information_t
 return all information about a provider More...

struct  TSP_consumer_symbol_info_t
 Structure used to read all symbols info. More...

struct  TSP_consumer_symbol_requested_t
 Structure used to request symbols. More...

struct  TSP_sample_t
 Structure to get each sample. 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_sample_callback_t )(TSP_sample_t *sample, void *user_data)
 Callback function type used to receive a sample item.

typedef void * TSP_provider_t
 Opaque handle type for provider.


Enumerations

enum  TSP_consumer_status_t
 Status for a futur get_last_error function. More...


Functions

int TSP_consumer_init (int *argc, char **argv[])
 Initialisation for TSP library.

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

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.

TSP_provider_tTSP_consumer_connect_url (const char *url)
const char * TSP_consumer_get_connected_name (TSP_provider_t provider)
 Request provider name.

void TSP_consumer_disconnect_one (TSP_provider_t provider)
 Disconnect one given provider.

int TSP_consumer_request_open (TSP_provider_t provider, int custom_argc, char *custom_argv[])
 Ask the provider for a new consumer session.

int TSP_consumer_request_close (TSP_provider_t provider)
 Close the session.

int TSP_consumer_request_information (TSP_provider_t provider)
 Request provider information.

const TSP_consumer_information_tTSP_consumer_get_information (TSP_provider_t provider)
 Retrieve the provider list.

int TSP_consumer_request_sample (TSP_provider_t provider, TSP_consumer_symbol_requested_list_t *symbols)
 Ask the provider for a list of symbols.

const TSP_consumer_symbol_requested_list_t * TSP_consumer_get_requested_sample (TSP_provider_t provider)
 Retrieve the symbols requested list.

int TSP_consumer_request_sample_init (TSP_provider_t provider, TSP_sample_callback_t callback, void *user_data)
 Prepare and start the sampling sequence.

int TSP_consumer_request_sample_destroy (TSP_provider_t provider)
 Stop and destroy the sampling sequence.

int TSP_consumer_read_sample (TSP_provider_t provider, TSP_sample_t *sample, int *new_sample)
 Read a sample symbol.


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

Definition at line 206 of file tsp_consumer.h.


Typedef Documentation

typedef void* TSP_provider_t
 

Opaque handle type for provider.

Definition at line 143 of file tsp_consumer.h.

Referenced by tsp_ascii_writer_validate_symbols(), TSP_consumer_connect_all(), TSP_consumer_connect_url(), TSP_consumer_disconnect_all(), TSP_consumer_disconnect_one(), TSP_consumer_get_connected_name(), TSP_consumer_get_information(), TSP_consumer_get_requested_sample(), TSP_consumer_read_sample(), TSP_consumer_request_close(), TSP_consumer_request_information(), TSP_consumer_request_open(), TSP_consumer_request_sample(), TSP_consumer_request_sample_destroy(), and TSP_consumer_request_sample_init().

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);

Definition at line 81 of file tsp_consumer.h.

Referenced by TSP_consumer_request_sample_init(), and TSP_data_receiver_create().


Enumeration Type Documentation

enum TSP_consumer_status_t
 

Status for a futur get_last_error function.

FIXME : not used for now. Anyway, this enum must be completed

Definition at line 56 of file tsp_consumer.h.


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

Definition at line 542 of file tsp_consumer.c.

References TSP_get_server_max_number(), and TSP_provider_t.

TSP_provider_t* TSP_consumer_connect_url const char *  url  ) 
 

Definition at line 398 of file tsp_consumer.c.

References TSP_get_server_max_number(), and TSP_provider_t.

Referenced by tsp_ascii_writer_validate_symbols().

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

Definition at line 607 of file tsp_consumer.c.

References TSP_consumer_disconnect_one(), TSP_get_server_max_number(), and TSP_provider_t.

void TSP_consumer_disconnect_one TSP_provider_t  provider  ) 
 

Disconnect one given provider.

Definition at line 525 of file tsp_consumer.c.

References TSP_provider_t, and TSP_remote_close_server().

Referenced by TSP_consumer_disconnect_all().

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.

Definition at line 381 of file tsp_consumer.c.

Referenced by tsp_ascii_writer_finalise().

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

Definition at line 643 of file tsp_consumer.c.

References TSP_provider_t.

Referenced by tsp_ascii_writer_validate_symbols().

const TSP_consumer_information_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

Definition at line 855 of file tsp_consumer.c.

References TSP_CHECK_SESSION, and TSP_provider_t.

Referenced by tsp_ascii_writer_validate_symbols().

const TSP_consumer_symbol_requested_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.

Definition at line 999 of file tsp_consumer.c.

References TSP_CHECK_SESSION, and TSP_provider_t.

Referenced by get_index2vars_size(), init_tsp_index(), and tsp_ascii_writer_start().

int 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:
TRUE = OK

Definition at line 269 of file tsp_consumer.c.

Referenced by tsp_ascii_writer_initialise().

int 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:
TRUE or FALSE. FALSE = There is an error (but we can not know it for now).

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.

Definition at line 1177 of file tsp_consumer.c.

References TSP_sample_t::provider_global_index, TSP_DUMMY_PROVIDER_GLOBAL_INDEX_CONSUMER_DATA_LOST, TSP_DUMMY_PROVIDER_GLOBAL_INDEX_EOF, TSP_DUMMY_PROVIDER_GLOBAL_INDEX_GLU_DATA_LOST, TSP_DUMMY_PROVIDER_GLOBAL_INDEX_RECEIVER_ERROR, TSP_DUMMY_PROVIDER_GLOBAL_INDEX_RECONF, and TSP_provider_t.

Referenced by tsp_ascii_writer_start().

int TSP_consumer_request_close TSP_provider_t  provider  ) 
 

Close the session.

Parameters:
provider The provider handle
Returns:
TRUE or FALSE. TRUE = OK.

Definition at line 726 of file tsp_consumer.c.

References TSP_CHECK_SESSION, TSP_provider_t, TSP_request_close(), and TSP_VERSION.

int 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:
TRUE or FALSE. TRUE = OK.

Definition at line 764 of file tsp_consumer.c.

References TSP_CHECK_SESSION, TSP_provider_t, and TSP_VERSION.

Referenced by tsp_ascii_writer_validate_symbols().

int 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 succed 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:
TRUE or FALSE. TRUE = OK. 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.

Definition at line 651 of file tsp_consumer.c.

References TSP_request_open_t::argv, TSP_answer_open_t::channel_id, TSP_answer_open_t::status, TSP_answer_open_t::status_str, TSP_provider_t, TSP_VERSION, and TSP_request_open_t::version_id.

Referenced by tsp_ascii_writer_validate_symbols().

int TSP_consumer_request_sample TSP_provider_t  provider,
TSP_consumer_symbol_requested_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:
TRUE or FALSE. TRUE = OK.

Definition at line 907 of file tsp_consumer.c.

References TSP_CHECK_SESSION, TSP_group_create_group_table(), TSP_provider_t, and TSP_VERSION.

Referenced by tsp_ascii_writer_validate_symbols().

int TSP_consumer_request_sample_destroy TSP_provider_t  provider  ) 
 

Stop and destroy the sampling sequence.

Parameters:
provider The provider handle
Returns:
TRUE or FALSE. TRUE = OK.

Definition at line 1114 of file tsp_consumer.c.

References TSP_CHECK_SESSION, TSP_data_receiver_destroy(), TSP_data_receiver_prepare_stop(), TSP_data_receiver_stop(), TSP_provider_t, and TSP_VERSION.

Referenced by tsp_ascii_writer_finalise().

int 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:
TRUE or FALSE. TRUE = OK.

Definition at line 1050 of file tsp_consumer.c.

References TSP_CHECK_SESSION, TSP_CONSUMER_RINGBUF_SIZE, TSP_data_receiver_create(), TSP_provider_t, TSP_sample_callback_t, and TSP_VERSION.

Referenced by tsp_ascii_writer_start().

Framework Home Page.


Beware !! TSP wave is coming...