TSP: The Transport Sample Protocol



GLU Library
[Provider Core Library]

Collaboration diagram for GLU Library:The GLU is the part of the TSP provider that should be coded each time the underlying 'real' sampled system (hardware card, simulator, . More...


Modules

 GLU Default Instance
 The default GLU API implements default function that are suitable for a 'simple' GLU object.

Data Structures

struct  GLU_handle_t
 GLU handle object. More...
struct  glu_item_t
 Item used to transmit a sample data from the GLU to the datapool of the TSP provider lib. More...

Defines

#define TSP_ASYNC_WRITE_ALLOWED   1
 Asynchronous write "allowed" value.
#define TSP_ASYNC_WRITE_FORBIDDEN   0
 Asynchronous write "forbidden" value.

Typedefs

typedef int32_t(*) GLU_async_sample_read_ft (struct GLU_handle_t *cthis, int32_t pgi, void *value_ptr, uint32_t *value_size)
 GLU asynchronous sample read.
typedef int32_t(*) GLU_async_sample_write_ft (struct GLU_handle_t *cthis, int32_t pgi, void *value_ptr, uint32_t value_size)
 GLU asynchronous sample write.
typedef double(*) GLU_get_base_frequency_ft (struct GLU_handle_t *cthis)
 Default GLU base frequency.
typedef int32_t(*) GLU_get_filtered_ssi_list_ft (struct GLU_handle_t *cthis, int32_t filter_kind, char *filter_string, TSP_answer_sample_t *symbol_list)
 Filtered list of symbols managed by the GLU.
typedef GLU_handle_t *(*) GLU_get_instance_ft (struct GLU_handle_t *cthis, int32_t custom_argc, char *custom_argv[], char **error_info)
 GLU instance creation.
typedef int32_t(*) GLU_get_nb_max_consumer_ft (struct GLU_handle_t *cthis)
 The maximum number of consumer connection.
typedef int32_t(*) GLU_get_nb_symbols_ft (struct GLU_handle_t *cthis)
 Get the number of symbols managed by the GLU.
typedef int32_t(*) GLU_get_pgi_ft (struct GLU_handle_t *cthis, TSP_sample_symbol_info_list_t *symbol_list, int *pg_indexes)
 GLU_get_provider_global_indexes provider global indexes corresponding to given symbol list.
typedef char *(*) GLU_get_server_name_ft (struct GLU_handle_t *cthis)
 GLU server name getter.
typedef GLU_server_type_t(*) GLU_get_server_type_ft (struct GLU_handle_t *cthis)
 GLU server type getter.
typedef int32_t(*) GLU_get_ssei_list_fromPGI_ft (struct GLU_handle_t *cthis, int *pgis, int32_t pgis_len, TSP_sample_symbol_extended_info_list_t *SSEI_list)
 Get Sample Symbols Extended Info list from PGI lists.
typedef int32_t(*) GLU_get_ssi_list_fromPGI_ft (struct GLU_handle_t *cthis, int *pgis, int32_t pgis_len, TSP_sample_symbol_info_list_t *SSI_list)
 Get Sample Symbols Info list from PGI lists.
typedef int32_t(*) GLU_get_ssi_list_ft (struct GLU_handle_t *cthis, TSP_sample_symbol_info_list_t *symbol_list)
 List of symbols managed by the GLU.
typedef int32_t(*) GLU_init_ft (struct GLU_handle_t *cthis, int32_t fallback_argc, char *fallback_argv[])
 GLU initialization function.
typedef void *(*) GLU_run_ft (void *cthis)
 Start the loop that will push data to datapool with push_next_item.
typedef int32_t(*) GLU_start_ft (struct GLU_handle_t *cthis)
 Start push datapool GLU activity AS A SEPARATE thread.

Enumerations

enum  GLU_get_state_t {
  GLU_GET_NEW_ITEM, GLU_GET_NO_ITEM, GLU_GET_EOF, GLU_GET_RECONF,
  GLU_GET_DATA_LOST
}
 The state of the GLU. More...
enum  GLU_server_type_t { GLU_SERVER_TYPE_ACTIVE, GLU_SERVER_TYPE_PASSIVE }
 GLU server type. More...

Functions

int32_t GLU_handle_check (GLU_handle_t *glu)
 Check a GLU_handle for consistency.
BEGIN_C_DECLS _EXPORT_TSP_PROVIDER
int32_t 
GLU_handle_create (GLU_handle_t **glu, const char *name, const GLU_server_type_t type, const double base_frequency)
 Create a GLU_handle.
int32_t GLU_handle_destroy (GLU_handle_t **glu)
 Destroy a GLU_handle.


Detailed Description

The GLU is the part of the TSP provider that should be coded each time the underlying 'real' sampled system (hardware card, simulator, .

..) change. The GLU object interface GLU_handle_t should be implemented in order to combine the TSP provider lib in a real TSP provider.


Define Documentation

#define TSP_ASYNC_WRITE_ALLOWED   1

Asynchronous write "allowed" value.

#define TSP_ASYNC_WRITE_FORBIDDEN   0

Asynchronous write "forbidden" value.


Typedef Documentation

typedef int32_t(* ) GLU_async_sample_read_ft(struct GLU_handle_t *cthis, int32_t pgi, void *value_ptr, uint32_t *value_size)

GLU asynchronous sample read.

This function will be called by the provider for each TSP_async_sample_read. The convention fixed is : if we can write with this function the sample represented by its provider_global_index (correct pgi and authorization by the GLU), the number returned is >0; else the number returned is <= 0

Parameters:
[in] pgi the index of the symbol concerned by the writing
[in] value_ptr the new value of the symbol
[in,out] value_size the size of the value.
Returns:
>0 on success <=0 on failure

typedef int32_t(* ) GLU_async_sample_write_ft(struct GLU_handle_t *cthis, int32_t pgi, void *value_ptr, uint32_t value_size)

GLU asynchronous sample write.

This function will be called by the provider for TSP_async_sample_write. The convention fixed is : if we can write with this function the sample represented by its provider_global_index (correct pgi and authorization by the GLU), the number returned is >0; else the number returned is <= 0

Parameters:
[in] pgi the index of the symbol concerned by the writing
[in] value_ptr the new value of the symbol
[in] value_size the size of the value.
Returns:
>0 on success <=0 on failure

typedef double(* ) GLU_get_base_frequency_ft(struct GLU_handle_t *cthis)

Default GLU base frequency.

Returns:
GLU base frequency (Hz)

typedef int32_t(* ) GLU_get_filtered_ssi_list_ft(struct GLU_handle_t *cthis, int32_t filter_kind, char *filter_string, TSP_answer_sample_t *symbol_list)

Filtered list of symbols managed by the GLU.

Parameters:
[in] cthis Handle for the GLU (when the GLU is ACTIVE, it is always equal to GLU_GLOBAL_HANDLE)
[in] filter_kind the filter kind
[in] filter_string the filter string
[out] ans_sample the answer_sample to be filled-in by the GLU.
Returns:
TRUE of FALSE. TRUE = OK;

typedef struct GLU_handle_t*(* ) GLU_get_instance_ft(struct GLU_handle_t *cthis, int32_t custom_argc, char *custom_argv[], char **error_info)

GLU instance creation.

This function will be called by the provider for each consumer connection. This function is the place where the GLU must be instanciated.

Parameters:
custom_argc Number of consumer initialisation elements (when the consumer do not provide any parameters this parameter is equal to fallback_argc of GLU_init)
custom_argv Initialisation elements The first usefull parameter is always fallback_argv[1], so as the getopt* functions may be used to parse those parameters (when the consumer do not provide any parameters this parameter is equal to fallback_argv of GLU_init)
error_info When the function fail the GLU may use this parameter to return an error string that will be transmited to the consumer to get detailed information about the error.
Returns:
The created GLU handle. Returns 0 when the function fail

typedef int32_t(* ) GLU_get_nb_max_consumer_ft(struct GLU_handle_t *cthis)

The maximum number of consumer connection.

Returns:
maximum number of consumer connection

typedef int32_t(* ) GLU_get_nb_symbols_ft(struct GLU_handle_t *cthis)

Get the number of symbols managed by the GLU.

Parameters:
this Handle for the GLU (when the GLU is ACTIVE, it is always equal to GLU_GLOBAL_HANDLE)
Returns:
the number of symbols;

typedef int32_t(* ) GLU_get_pgi_ft(struct GLU_handle_t *cthis, TSP_sample_symbol_info_list_t *symbol_list, int *pg_indexes)

GLU_get_provider_global_indexes provider global indexes corresponding to given symbol list.

Used to validate client provided symbol list

Parameters:
[in] symbol_list the symbol list to validate
[out] pg_indexes array containing corresponding provider global indexes or -1 if not found
Returns:
TRUE if all symbol found, else return FALSE

typedef char*(* ) GLU_get_server_name_ft(struct GLU_handle_t *cthis)

GLU server name getter.

This string will be used by the consumers to get informations about a provider. It must be meaningfull (ex : "Temperatures Sampler" )

typedef GLU_server_type_t(* ) GLU_get_server_type_ft(struct GLU_handle_t *cthis)

GLU server type getter.

Will get the GLU type i.e. ACTIVE or PASSIVE.

Returns:
GLU server type.

typedef int32_t(* ) GLU_get_ssei_list_fromPGI_ft(struct GLU_handle_t *cthis, int *pgis, int32_t pgis_len, TSP_sample_symbol_extended_info_list_t *SSEI_list)

Get Sample Symbols Extended Info list from PGI lists.

Parameters:
[in] cthis Handle for the GLU (when the GLU is ACTIVE, it is always equal to GLU_GLOBAL_HANDLE)
[in] pgis the array of requested PGI
[in] pgis_len the length of the pgis array
[in,out] on entry the preallocated SSEI list, on return the updated SSEI list
Returns:
TRUE of FALSE. TRUE = OK;

typedef int32_t(* ) GLU_get_ssi_list_fromPGI_ft(struct GLU_handle_t *cthis, int *pgis, int32_t pgis_len, TSP_sample_symbol_info_list_t *SSI_list)

Get Sample Symbols Info list from PGI lists.

Parameters:
[in] cthis Handle for the GLU (when the GLU is ACTIVE, it is always equal to GLU_GLOBAL_HANDLE)
[in] pgis the array of requested PGI
[in] pgis_len the length of the pgis array
[in,out] the preallocated SSI list.
Returns:
TRUE of FALSE. TRUE = OK;

typedef int32_t(* ) GLU_get_ssi_list_ft(struct GLU_handle_t *cthis, TSP_sample_symbol_info_list_t *symbol_list)

List of symbols managed by the GLU.

Parameters:
this Handle for the GLU (when the GLU is ACTIVE, it is always equal to GLU_GLOBAL_HANDLE)
symbol_list List of symbols
Returns:
TRUE of FALSE. TRUE = OK;

typedef int32_t(* ) GLU_init_ft(struct GLU_handle_t *cthis, int32_t fallback_argc, char *fallback_argv[])

GLU initialization function.

The code in this function will be called once, and may do any usefull global check and initialization. Usually the data stream should not be started in this function as there is no connected consumer when this function is called. To start your data stream, wait for the first GLU_get_instance function that will be called for each consumer connection

The parameters for this function come from the parameters that may have been provided thrue the command line that was used to launch the provider. In this function the GLU should not use these parameters, but it should check their value, as these value will be used as fallback parameters for the GLU_get_instance function each time a consumer connect to the provider and does not provide its own parameters

the GLU may then for this function return :

NOTE1 : Sometimes, the the only way to check the provided parameters is to start the data stream. If so, the data stream must not be started a second time in the get_instance function.

NOTE2 : This string is provided in this function for fallback test only and should not be memorized by the GLU server

NOTE3 : When there is not fallback stream at all, the value of fallback_argv is 0. It is up to the GLU server to decide if it is acceptable for the provider to be started with no fallback stream at all (it usually is acceptable)

Parameters:
this,the GLU handle
fallback_argc Number of fallback initialisation elements as used in main(argc, argv)
fallback_argv Fallback initialisation elements as used in main(argc, argv) The first usefull parameter is always fallback_argv[1], so as the getopt* functions may be used to parse those parameters
Returns:
Return FALSE if a fatal error occur during initialisation or if there is a probleme with the provided parameters

typedef void*(* ) GLU_run_ft(void *cthis)

Start the loop that will push data to datapool with push_next_item.

Returns:
status

typedef int32_t(* ) GLU_start_ft(struct GLU_handle_t *cthis)

Start push datapool GLU activity AS A SEPARATE thread.

The start function should NOT block, the defaut implementation is to start a new thread running the 'GLU_run_ft' of the GLU.

Returns:
0 on success and other value on error.


Enumeration Type Documentation

enum GLU_get_state_t

The state of the GLU.

Enumerator:
GLU_GET_NEW_ITEM  new item available
GLU_GET_NO_ITEM  no item available
GLU_GET_EOF  end of data stream
GLU_GET_RECONF  end of data stream, and GLU list of symbols changed, all client will have to ask fo the new symbol list
GLU_GET_DATA_LOST  Data were lost in GLU internals ; The provider might be too slow and/or the GLU too fast, and/or the CPU overloaded : all clients will be notified by the provider.

enum GLU_server_type_t

GLU server type.

Enumerator:
GLU_SERVER_TYPE_ACTIVE  GLU is active.

Means that the data are continuously produced and must be read at the same pace (or faster) by the provider. When GLU is active their shouldn'tr be more that one GLU instance running by provider.

See also:
GLU_get_instance.
GLU_SERVER_TYPE_PASSIVE  GLU is passive.

Means that the data are produced only when the provider ask for them (typically File Based Glu/Provider)


Function Documentation

int32_t GLU_handle_check ( GLU_handle_t glu  ) 

Check a GLU_handle for consistency.

This function may be called after specific GLU initialisation in order to verify member function pointer consistency and values:

Parameters:
[in] glu the GLU_handle object to be checked.
Returns:
TRUE if ok FALSE otherwise

BEGIN_C_DECLS _EXPORT_TSP_PROVIDER int32_t GLU_handle_create ( GLU_handle_t **  glu,
const char *  name,
const GLU_server_type_t  type,
const double  base_frequency 
)

Create a GLU_handle.

This will provide some default implementation for member function.

Parameters:
[out] glu pointer to a GLU_handle pointer that will be allocated
[in] name the name of the GLU that will be advertised by the TSP provider.
[in] type the type of the GLU
See also:
GLU_server_type_t
Parameters:
[in] base_frequency the base frequency that will be advertised by the TSP provider
Returns:
TRUE if ok FALSE otherwise

int32_t GLU_handle_destroy ( GLU_handle_t **  glu  ) 

Destroy a GLU_handle.

Parameters:
[out] glu pointer to a GLU_handle pointer that will be allocated
Returns:
TRUE if ok FALSE otherwise

Framework Home Page.


Beware !! TSP wave is coming...