Routines for a callback routine of a service
Add an information service to the list of provided services.
unsigned int dis_add_service (name, description, address, size, user_routine, tag)
char *name;
Service name, this name should be used by the client when requesting the service.char *description;
Service description string, the contents of the service can be described in this form.int *address;
Service address, if the data provided by this service is stored in memory (global section, array, etc) and is to be sent as it is to the client, it's address should be given here.int size;
Service size, the size in bytes of the data to be passed to the client if the previous parameter has been specified.void *user_routine;
The address of a routine to be executed when it's time to send the data to a client. This routine will provide the data, the parameters of this routine will be specified later in this document.long tag;
A parameter to be sent to the user_routine in order to identify the service.
unsigned int service_id;
The service identifier, to be used when (if) updating or removing the service (by calling dis_update_service or dis_remove_service).
This routine has to be called once for every service provided by the server. There are two ways of providing the service : specifying the address and size of the data to be sent to the client or specifying the address of a routine that will provide the data.
Report the change of service contents to interested clients.
int dis_update_service (service_id)
unsigned int service_id;
The service_id returned by dis_add_service.
int n_clients;
Returns the number of updated clients.
This routine should be called by the server program when there is a change for a given service (when possible).
This routine will check whether there are clients interested in this service and if they have requested to receive the data upon change (monitored service) the data will be sent, either by calling the data provider routine or by sending the specified data buffer.
Report the change of service contents to selected clients.
int dis_selective_update_service (service_id, client_ids)
unsigned int service_id;
The service_id returned by dis_add_service.
int *client_ids;
An array of client_ids, terminated by '0' for which the service should be updated.
int n_clients;
Returns the number of updated clients.
This routine should be called by the server program if only one or a subset of the clients should be updated, for example in response to a command received from a particular client.
Client ids can be obtained using dis_get_client().
Sets the quality of a service that is published to interested clients.
void dis_set_quality (service_id, quality)
unsigned int service_id;
The service_id returned by dis_add_service().
int quality;
A flag for the quality of a service.
This routine can be called by a DIM server to set the quality flag of a service. Normally just before updating the service.
If a DIM client subscribes to a service using the routine dic_info_service_stamped(), the quality flag will be published together with the updated service data. The client can obtain the quality flag by using the routine dic_get_quality().
Sets the time stamp of a service that is published to interested clients.
void dis_set_timestamp(service_id, secs, millisecs)
unsigned int service_id;
The service_id returned by dis_add_service().
int secs;
Seconds since January 1, 1970.
int millisecs;
Milliseconds, a value between 0 and 999.
This routine can be called by a DIM server to set an explicit time stamp of a service. If this routine is not(!) used, a DIM server will automatically set the time stamp when the service is updated. After this routine has been used, the DIM server will only transfer the last time stamp, that has been set using this routine (no further automatic time stamping).
If a DIM client subscribes to a service using the routine dic_info_service_stamped(), the timestamp will be published together with the updated service data. The client can obtain the time stamp flag by using the routine dic_get_timestamp().
Remove a Service from the list of provided services.
int dis_remove_service (service_id)
unsigned int service_id;
The service_id returned by dis_add_service or by dis_add_cmnd.
int return_code;
Returns 1 if the Service was successfully removed.
This routine can be called by the server program when a service (or command service) stops being provided.
This routine will inform the Name server and all the clients using this service that it is no longer provided. The service can from then on be provided by another server.
Add a command service to the list of provided services.
unsigned int dis_add_cmnd (name, description, cmnd_user_routine, tag)
char *name;
Service name, same name used by client when requesting the execution of a command.char *description;
Service description string, the contents of the service can be described in this form.void *cmnd_user_routine;
The address of the routine to be executed when a command request is received from a client, the parameters of this routine will be specified later in this document. This parameter is optional, if it is specified as zero, the request will be queued and can be recovered later by calling the routine dis_get_next_cmnd.long tag;
A parameter to be passed to the cmnd_user_routine or to dis_get_next_cmnd in order to identify the command service.
unsigned int service_id;
The service identifier, to be used when (if) removing the service (by calling dis_remove_service).
This routine has to be called once for every command service provided by the server.
Get a command from the list of waiting command requests.
int dis_get_next_cmnd (tag, buffer, size)
long *tag;
This parameter returns the tag given to dis_add_cmnd, it allows the identification of the command.
int *buffer;
A buffer address where the command request is to be copied to.
int *size;
On entry this parameter contains the size of the buffer, on exit it contains the real size of the command request.
int return_code
Returns 0 if no command request is waiting for execution, -1 if the command request doesn't fit on the specified buffer (truncated) and 1 if the command as been copied successfully into the user buffer.
This routine has to be called by the user if no cmnd_user_routine address has been specified in dis_add_cmnd. It allows the user to get and execute the commands requested by a client.
Start handling client requests.
int dis_start_serving (task_name)
char *task_name;
Task name, a string identifying the server, used by the Name server to recognize the server as well as for monitoring and debugging purposes.
int return_code
Returns 1 if the list of services and commands were successfully sent to the Name Server, 0 otherwise.
This routine will register within the name_server all the services declared with dis_add_service and dis_add_cmnd.It will set up the server so that it will handle client requests.
It will also set up all the mechanisms so that when a service has to be sent to a client the user_routine that provides that service will be called or the data will be taken from the address and size provided in dis_add_service and sent to the client.
Stop Serving DIM Services.
void dis_stop_serving ()
This routine can be called by the server program in order to stop being a DIM Server.
Disable padding of received command services.
void void dis_disable_padding()
When _not_ to use this routine: If you want to map the data of a received command service to a pre-declared structure, DIM will do the "padding" of the data to match the structure as required by the platform where it is running. (for example if a char is followed by an int in the structure DIM will add three dummy bytes between the two).
When to _use_ this routine: If you like to advance a pointer over a received buffer and cast the data by yourself, then padding should be disabled.
If padding should be disabled, this routine has to be called at the beginning of a program (before any other DIM calls).
Set the DNS node name for a DIM server.
int dis_set_dns_node (node_name)
char *node_name
The node (or a list of nodes separated by commas) where the DNS is (possibly) running.
int return_code
Returns 1 if successful.
This routine can be called by a server program before publishing any services in order to programmatically declare the node where the DNS is running. If this call is not used the environment variable DIM_DNS_NODE will be used instead.
A list of node names separated by commas can be given as a parameter, in which case the server will use the first name server found running from the list.
Unlike dim_set_dns_node() this function allows using different DIM Name Servers (DNSs) for the client and server part of a process.
Get the DNS node name for a DIM server
int dis_get_dns_node (node_name)
char *node_name
Returns the node (or a list of nodes separated by commas) where the DNS is (possibly) running.
int return_code
Returns 1 if successful.
This routine can be called by a server program to find out where the DNS was defined to be running.
Set the DNS port number for a DIM server.
int dis_set_dns_port (port)
int port
The port number of the DNS.
int return_code
Returns 1 if successful.
This routine can be called by a server program before publishing any services, together with dis_set_dns_node() in order to programmatically declare the port number used by the DNS (if the DNS was started with a non-default port number by using the environment variable DIM_DNS_PORT). The default port number of the DNS is 2505.
Get the DNS port number for a DIM server.
int dis_get_dns_port ()
int port
Returns the DNS port number.
This routine can be called by a server program to find out what port number was defined for the DNS.
Add an exit handler to this server.
void dis_add_exit_handler (exit_user_routine)
void *exit_user_routine;
The address of a routine to be executed when the server sees a fatal error or receives an exit command.
If no exit handler is declared a DIM server will exit in the following circumstances:
- The DNS node is undefined
- Some of his services are already declared in DNS
- The DNS doesn't accept connections from this machine
- An EXIT command from the DNS has been received
- An EXIT command from a client has been received
If the user declares an exit handler it is his/her responsibility to decide whether or not to exit.
Add an exit handler that can be called when a client disconnects.
void dis_add_client_exit_handler (client_exit_user_routine)
void (*client_exit_user_routine);
The address of a routine to be executed when a client exits.
Specifies a user routine that can be called, when a DIM client exits. In order to activate the exit handler for a specific service for a specific client, you have to use the routine dis_set_client_exit_handler.
Add an error handler to this server.
void dis_add_error_handler (error_user_routine)
void *error_user_routine;
The address of a routine to be executed when the server sees an error.
If no error handler is declared a DIM server will print an error message on the standard output whenever it sees a problem.If the user declares an error handler the error message and its severity as well as an error code will be passed to the error_user_routine and the user can decide what to do with it.
Routine written by the user in order to provide a service.
void user_routine (tag, address, size)
long *tag;
The parameter that identifies the service, the tag given to dis_add_service. Passed by reference for FORTRAN compatibility.int **address;
Should return the address of the data to be sent to the client.int *size;
Should return the size in bytes of the data to be sent to the client
This routine should be declared in dis_add_service() if not using the address, size parameters, it will be called whenever the service has to be sent to the client.This routine should provide the necessary gathering or computing of data and store it in a buffer in order to be sent as a service to a client.
Routine written by the user in order to execute a command when a command request is received from a client.
void cmnd_user_routine (tag, address, size)
long *tag;
The parameter that identifies the command, the tag given to dis_add_cmnd. Passed by reference for FORTRAN compatibility.int *address;
The address of the buffer containing the command.int *size;
The size in bytes of the command data. Passed by reference for FORTRAN compatibility.
This routine should be declared in dis_add_cmnd() for immediate execution on reception of a command request.
Routine written by the user in order to implement an exit handler.
void exit_user_routine (code)
int *code;
The error code that caused the exit request or the code sent by the client, if the request came from a client.
Note: clients should not send exit codes lower than 0x100 in order not to be confused with the internal error codes
This routine should be declared by dis_add_exit_handler(). It is called whenever a fatal DIM error or an exit command is received. Normally it should cleanup and terminate the program, but the user can check the code and decide otherwise.
Routine written by the user in order to implement an error handler.
void error_user_routine (severity, error_code, message)
int severity;
A severity code: 0 - info, 1 - warning, 2 - error, 3 - fatal.
int error_code;
An error code.
char *message;
The error message explaining the detected error.
This routine should be declared by dis_add_error_handler(). It is called whenever an error is detected by DIM. Normally it should print or store the error as the user finds convenient.
Routine written by the user in order to implement an exit handler that is called, when a client disconnects from a service.
void client_exit_user_routine (tag)
int *tag;
The tag that has been specified, when the client exit handler has been activated using dis_set_client_exit_handler.
This routine should be declared by dis_add_client_exit_handler(). It is called whenever a DIM client disconnects from a DIM service.
Gets the process identification of the current DIM client.
int dis_get_client (name)
char *name;
Process ID of the DIM client process from which a command is being received or for which a service is being updated. The format of the process ID is "PID@NODENAME".
int conn_id;
Returns the client_id, in terms of its connection id, or 0 if no client is currently being handled;
This routine should be called inside the command callback or the server callback routine when a command is being received or service data is being updated.
It obtains the process ID of the client in the format "PID@NODENAME" and the client_id as return value.
Gets the connection ID of the current DIM client.
int dis_get_conn_id ()
int conn_id;
Returns the conn_id of a DIM client
This routine should be called inside a server callback routine when service data is being requested from a client. Its purpose is to obtain the conn_id that is required by other routines.
Gets the update rate that was specified by a client for a specific service.
int dis_get_timeout (service_id, client_id)
unsigned int service_id;
The service_id returned by dis_add_service or by dis_add_cmnd.
int conn_id;
conn_id of a DIM client as obtained by the routine dis_get_conn_id.
int timeout;
Returns the update rate [s] that was specified by the client
This routine should be called inside a server callback routine when service data is being requested from a client. Its purpose is to return the update rate that was requested by the specified client for the specified service..
Gets the services of a DIM client, which has subscribed to this DIM server.
char *dis_get_client_services (conn_id)
int conn_id;
conn_id of a DIM client as obtained by the routine dis_get_conn_id.
char *services
Returns a list of services of the specified client, which has subscribed to this DIM server.
This routine should be called inside a server callback routine when service data is updated. Its purpose is to get a list of all services, to which the a DIM client has subscribed. The list contains only the services of the specified client.
Activates the client exit handler for a specific client and a specific service.
void dis_set_client_exit_handler (conn_id, tag)
int conn_id;
The connection ID of a specific client.
int tag
A tag that is passed to the user_routine, when the client exits.
Activates the client exit handler for a specific client and a specific service. The user routine has to be defined using the routine dis_add_client_exit_handler.
Comment: It is not really required to call this routine inside a command callback routine. But the only way to get the conn_id of the client is by using the routines dis_get_client or dis_get_conn_id, which are only available inside a callback routine.
Gets the names of DIM services that have an error.
char *dis_get_error_services ()
char *services;
Returns a list of services, that originated the error.
This routine should be called inside the error_user_routine to find out, which service(s) have an error.