A remote procedure call can only work if an interface definition that clearly defines operation signatures exists. Operation signatures define the syntax for an operation, including its name and parameters (input and output) that are passed as part of the procedure call. The TP process interface exports the two operation signatures that have been previously explained. The interface is provided in the file examples/dts/dtsprovider.idl. When building the TP process application, this file must be compiled using the IDL compiler, which creates three files:
· dtsprovider.h (header file)
· dtsprovider_sstub.c (server stub file)
· dtsprovider_cstub.c (client stub file)
The Time-Provider program (TP program) must be compiled along with the dtsprovider_sstub.c code and then linked together. The TP program must also include the stub-generated file dtsprovider.h. The following sample code shows the structure of this interface.
/*
* Time Service Provider Interface
*
* This interface is defined through the Network Interface
* Definition Language (NIDL).
*/
[uuid (bfca1238-628a-11c9-a073-08002b0dea7a),
version(1)
]
interface time_provider
{
import "dce/nbase.idl";
import "dce/utctypes.idl";
/* Minimum and Maximum number of times to read time source at
* each synchronization
*/
const long K_MIN_TIMESTAMPS = 1;
const long K_MAX_TIMESTAMPS = 6;
/* Message status field return values
*/
const long K_TPI_FAILURE = 0;
const long K_TPI_SUCCESS = 1;
/* This structure contains one reading of the TP wrapped in
* the timestamps of the local clock.
*/
typedef struct TimeResponseType
{
utc_t beforeTime; /* local clk just before getting UTC */
utc_t TPtime; /* source UTC; inacc also supplied */
utc_t afterTime; /* local clk just after getting UTC */
} TimeResponseType;
/* Time-provider control message. This structure is returned
* in response to a time service request. The status field
* returns TP success or failure. The nextPoll gives the
* client the time at which to poll the TP next. The timeout
* value tells the client how long to wait for a time response
* from the TP. The noClockSet will tell the client whether
* or not it is allowed to alter the system clock after a
* synchronization with the TP.
*/
typedef struct TPctlMsg
{
unsigned long status;
unsigned long nextPoll;
unsigned long timeout;
unsigned long noClockSet;
} TPctlMsg;
/* TP timestamp message. The actual time-provider
* synchronization data. The status is the result of the
* operation (success or failure). The timeStampCount
* parameter returns the number of timestamps being returned
* in this message. The timeStampList is the set of
* timestamps being returned from the TP.
*/
typedef struct TPtimeMsg
{
unsigned long status;
unsigned long timeStampCount;
TimeResponseType timeStampList[K_MAX_TIMESTAMPS];
} TPtimeMsg;
/* The Time-Provider Interface structures are described here.
* There are two types of response messages from the TP:
* control message and data message.
*
* <<<< TPI CONTROL MESSAGE >>>>
*
* 31 0
* +-------- - ---------------------------------+
* | Time-Provider Status |
* +--------------------------------------------+
* | Next Poll Delta |
* +--------------------------------------------+
* | Message Time Out |
* +--------------------------------------------+
* | NoSet Flag |
* +--------------------------------------------+
*
* <<<< a single timestamp >>>>
*
* 128 0
* +--------------------------------------------+
* | Before Time |
* +--------------------------------------------+
* | TP Time |
* +--------------------------------------------+
* | After Time |
* +--------------------------------------------+
*
* <<<< TPI DATA MESSAGE >>>>
*
* 31 0
* +--------------------------------------------+
* | Time-Provider Status |
* +--------------------------------------------+
* | Timestamp Count |
* +--------------------------------------------+
* | |
* | <timestamp one> |
* | |
* +--------------------------------------------+
* | . |
* | . |
* | . |
* | . |
* | . |
* +--------------------------------------------+
* | |
* | <timestamp K_MAX_TIMESTAMPS> |
* | |
* +--------------------------------------------+
*/
/* The RPC-based Time-Provider Program (TPP) interfaces are
* defined here. These calls are invoked by a Time Service
* daemon running as a server (in this case it makes an RPC
* client call to the TPP server).
*/
/* CONTACT_PROVIDER
* Send initial contact message to the TPP. The TPP server
* responds with a control message.
*/
void ContactProvider
(
[in] handle_t bind_h,
[out] TPctlMsg *ctrlRespMsg,
[out] error_status_t *comStatus
);
/* SERVER_REQUEST_PROVIDER_TIME
* The client sends a request to the TPP for times. The
* TPP server responds with an array of timestamps obtained
* by querying the Time-Provider hardware that it polls.
*/
void ServerRequestProviderTime
(
[in] handle_t bind_h,
[out] TPtimeMsg *timesRspMsg,
[out] error_status_t *comStatus
);
}