Product:

ZDK

Category:

Data

Subject:

Usage of H.224 Packets in Zydacron

Page:

1 of 1


Usage of H.224 Packets in Zydacron

This is an outline of how H.224 packets are routed and accessed in Zydacron’s ZHDLL.DLL. This will explain the track of the packets as they come in and then as they leave. It will also describe how to register an application to use this mechanism.

The modules involved are:

ZQ922.DLL

ZHDLL.DLL

The headers involved are:

ZQ922.H

ZHDLL.H

Registration

A client is a set of routines and data buffers that register with ZHDLL to send and receive data packets through the H.224 mechanism.

A module wanting to receive packets registers with ZHDLL through the function ZHDLL_Register(), defined in ZHDLL.C and prototyped in ZHDLL.H. This function is called with the client ID to associate with the packets, the extra capabilites of the client, the packet callback function, and the callback registration function. The prototype looks like this:

LPZHDLL_CLIENT CALLBACK ZHDLL_Register

(

LPVOID client_parameter, /* passed through to the callbacks */

LPBYTE client_id,

int n_bytes_extra_capabilities,

LPBYTE extra_capabilities,

ZHDLL_RECEIVE_CALLBACK receive_callback,

ZHDLL_REGISTER_CALLBACK register_callback

);

The value returned is the LPZHDLL_CLIENT value to use with every subsequent ZHDLL function call.

The client_parameter is provided as a mechanism to pass data internally to the client. It is not used by ZHDLL.

The client_id is contained within the packet. When a packet is received the list of registered clients is searched for a client that has a client ID that matches the one contained within the received packet.

The extra_capabilities parameter value is sent to the far end when a connection is made to identify the capabilities of the registered client. The parameter n_bytes_extra_capabilities is the number of bytes in the extra capabilities buffer.

The parameters receive_callback and register_callback are functions called by ZHDLL.

The function to receive data packets, passed as parameter receive_callback, is called when available data is processed and passed to the client that registered for the data. It needs this prototype:

void ZHFECC_EXPORT CALLBACK ZH_ReceiveCallback

(

LPVOID client_parameter,/* value we gave to ZHDLL_Register */

int source_address, /* who the packet is from */

int n_bytes, /* bytes in 'payload' */

LPBYTE payload, /* the data with no H.DLL headers */

int high_priority,/* non-zero if high-priority */

int c1c0 /* bits in packet header each client controls */

);

The function passed as parameter register_callback is called when the far end registers itself for sending these types of packets. It is called when there is a notification received of an H.224 client on the far end that is using the same client ID as the local client. It needs this prototype:

void ZHFECC_EXPORT CALLBACK ZH_RegisterCallback

(

LPVOID client_parameter, /* value we gave to ZHDLL_Register */

int source_address, /* who the packet is from */

int present, /* non-zero if client is present */

int n_bytes_extra_capabilities, /* zero if no extra caps */

LPBYTE extra_capabilities /* client-specific caps */

);

It is important that an application register only once before calling ZHDLL_Deregister(). Registering more than once without de-registering may cause problems.

Receiving Packets

The packet coming from the far end enters the HDLC controller. When data is available an interrupt is generated. Q.922 registers a function for use when the VXD services an interrupt. Q.922 loops around reading out of the VXD the packets that are available. Each packet is handled individually.

In the Q.922 layer the packets enter ReadPacketThread() and go into ZQ922_Recv(), each defined in ZQ922.C. The packet is then passed up and processed in PerformCallbackFromQ922(), defined in ZHDLL.C. ( This is refered to in ZQ922.C with the registerred callback pointer (*pClient->receive_callback)().) In 16-bit a message is posted for sending the packet to the function, while in 32-bit the function is called directory.

Packets enter ZHDLL.DLL through the function ZhdllPktRcv(), defined in zhdll_cb.c. It is given to the function ZHDLL_FindClientMatchingClientID(), defined in ZHDLL.C, sending as a parameter (&packet->packet.zhdll_client_id_start).

In here the size of the header is determined so that it can be examined. The algorithm for determining the size of the header is:

If byte 0 == ZHDLL_CLIENT_ID_EXTENDED (0x007E) then

Header size is 2

Else if byte 0 == ZHDLL_CLIENT_ID_NON_STANDARD (0x007F) then

Header size is 5

Else

Header size is 1

End if

In ZHDLL_FindClientMatchingClientID() it searches for the client this packet is assigned to. If a client is found for the packet, PerformCallbackFromQ922 () performs a series of error checks, then the packet is passed up to the receipt function of the registered client. The callback function is reference as client->receive_callback().

 

Sending Packets

Packets do not need to be assembled by the application client registered with ZHDLL. The client is only responsible for the data contained within the ‘payload’ buffer being sent to the far end.

A buffer of data is sent using the function ZHDLL_SendPacket() defined in ZHDLL.C. This function’s prototype is:

int CALLBACK ZHDLL_SendPacket

(

LPZHDLL_CLIENT client,

int destination_address,

int high_priority, /* zero for low priority, non-zero for high */

int n_bytes,

LPBYTE payload

)

This is simple to use. Specify the client, destination address, the buffer, and its size. ZHDLL assembles the packet and sends it to Q.922.

The client parameter is the value returned from ZHDLL_Register() and it identifies the client.

The destination_address parameter is the address, or ID, of the far end. For a point to point call it is always 0. Calls involving MCU’s may have different addresses for each participant in the call.

The high_priority parameter is the priority of the packet. The value !0 is high priority.

The parameter n_bytes is the size of the payload buffer in bytes.

The parameter payload is the data buffer to send to the far end.

When a packet is sent to the far end it enters the H.224 mechanism via ZHDLL_SendPacket(), defined in ZHDLL.C. In here information about the client is assembled and passed down to SendSegment(), also defined in ZHDLL.C.

In SendSegment() the headers are assembled and the packet is completely formed. It is then passed onto Q.922 through the function ZQ922_Send(), defined in ZQ922.C. Here there is some error checking and the packet is passed onto the VXD through the function ZQ922VxdWritePacket().

From here it is transmitted across the MLP channel to the far end.

De-Registration

When a client has completed any use of H.224 in the current task or process it needs to de-register itself with H.224. This is required, there is no option. If a client fails to de-register, the results are undefined.

A client DOES NOT need to de-register between phone calls. It only needs to do so when it is about to shut down.

ZHDLL_Deregister() has this prototype:

void CALLBACK ZHDLL_Deregister(LPZHDLL_CLIENT client);

This clears the callback pointers and de-allocates any buffers associated with the client.

Synopsis

To use H.224 with Zydacron follow these steps:

  1. Define two functions to receive H.224 data. Include ZHDLL.H in the source code.
  2. Load the ZHDLL.DLL file in your application.
  3. Register your client with ZHDLL using the function ZHDLL_Register().
  4. Make the videoconference phone call.
  5. If Zydacron to Zydacron, ensure that UART emulation is disabled. (See the special note below.)
  6. Send the string command to enable the H.224 mechanism "setcomm avc on channel to mlp protocol h224-on-q922".
  7. Open up an MLP data channel.
  8. Send data through ZHDLL_SendPacket() and receive data through your defined callback function.

Remember, there is no need to de-register and register between phone calls.

If you are using the classes or the custom control, you can skip steps 5-7, inclusively, by turning on FECC.

To shut down the H.224 mechanism, follow these steps:

  1. While in a call with H.224 active, shut down the data channel.
  2. Send the string to deactivate H.224 "setcomm avc off channel to mlp protocol h224-on-q922".
  3. If Zydacron to Zydacron turn UART emulation back on, if needed. (See special note below.)

If you are using LSD rather than MLP, replace any references to mlp with lsd in the MCI string commands. Also, open or close an LSD data channel where it is described to open or close an MLP channel.

When you are ready to terminate your application follow these steps:

  1. Be sure data is shut down as described above and the call is terminated.
  2. De-register your client by calling ZHDLL_Deregister().
  3. Terminate your application.

Special Note

If you are using H.224 between two Zydacron systems you will need to turn off UART emulation before data will work properly. Turning on FECC with either the classes or the custom control will shut down UART emulation correctly and the steps below will not be needed.

Here are the steps to turn off UART emulation:

  1. Be in a phone call with another Zydacron unit.
  2. This is important. Ensure that data is off on both sides of the call.
  3. On both sides, send the MCI string "message avc keep uart off".
  4. Be sure that both sides have sent this string before opening up any MLP channel and starting H.224.

If you wish to turn UART emulation back on so that automatic file transfers will work follow the above stops only change the MCI string to "message avc keep uart on".

 


Last reviewed: 11-Aug-97

THE INFORMATION PROVIDED BY ZYDACRON IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ZYDACRON EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

©1997 Zydacron, Inc. All rights reserved. Legal Notices.