3.4. Programming Interface
The module, described here, contains all H.245 capabilities uses in H.323 terminal, i.e.: signalling entities - their creation, destruction and management; waiting for primitives (from the user) and messages (from the network); supports timers, error checking, separate commands and indications. The main idea of this module is to allow the user send all signals to the H.245 subsystem and forget about its internal structure. In this implementation just one H.245 can be run. So this module can be used as a part of a terminal (not gatekeeper, MCU, etc).
Figure 3-7 shows what structures are used while communication with H.245 Subsystem is on. The mechanism used here is a set of queued primitives exchanged between the H.245 Subsystem and the Supervisory Thread. Type primitive_queue_p is a pointer to a queue where these primitives may be stored. It may be treated as a handler to a queue.
Full H.245 Subsystem API is presented in Figure 3-8.
Before H.245 Subsystem can be started, some actions must be taken. First, a return queue must be created. The return queue is used by H.245 Subsystem to send primitives to its user. To create this queue the following create_message_queue function is used.
Next, there must be an opened socket. The socket must be passed directly to the H.245 Subsystem to allow it to transmit and receive messages through it. This socket is usually opened by the user of subsystem. A special type socket_struct has been prepared to make this module portable. Now, H.245 can be started.
To do that, the user calls the start_H245 function. This function returns 0 if succeeds or non-zero if fails. The stop_h245 function can be used to stop H.245 Subsystem: The function returns zero if succeeds or non-zero if fails (e.g. no subsystem was previously run).
The send_h245_primitive routine is used by the user to send primitives to H.245 Subsystem. mt is the name of the primitive. message_params is a pointer to parameters (if any). Primitives can be also sent using send_h245_primitive_m. In this case mesg is a manually propared message containing a primitive in the field mt and a parameter in mesg. Until now the following primitives have been defined : H245_OPEN_LC (open logical channel), H245_CLOSE_LC (close logical channel), H245_MSD (start master slave determination), H245_CE (start capability exchange), H245_REQUEST_OPEN_LC (request open logical channel), H245_REQUEST_CLOSE_LC (request close logical channel), H245_REQUEST_CE (request capability exchange), H245_RTD (start round trip delay procedures). Some of these primitives do not require parameters, e.g.:
send_h245_primitive(H245_MSD, NULL); /* Start MSD procedures */The other require from user to fill a special structure (it differs for every primitive) and cast it on (void*) .
The get_h245_primitive function is used to acquire a primitive from the H.245 Subsystem. This function is a blocking one (if no parameters are in queue, it starts waiting until a parameter apppers). The function get_h245_primitive_nb is a non-blocking version of the get_h245_primitive routine (if no primitives are in the queue this function returns with EMPTY primitive). To get a primitive name get_message_type is used, and to get primitive parameter get_message_parameter is called.
Some more user-friendly API to this mechanism is being developed, e.g. open_logical_channel(codec_id), close_logical_channel(channel_num), ...