62471-10

100 Crossing BoulevardFramingham, MA 01702-5406 USA

www.nmscommunications.com

H.324M Interface Developer’s Reference Manual

P/N 9000-62471-10

H.324M Interface Manual

2 NMS Communications

No part of this document may be reproduced or transmitted in any form or by any means without prior written consent of NMS Communications Corporation.

© 2005 NMS Communications Corporation. All Rights Reserved.

Alliance Generation is a registered trademark of NMS Communications Corporation or its subsidiaries. NMS Communications, Natural MicroSystems, AG, CG, CX, QX, Convergence Generation, Natural Access, CT Access, Natural Call Control, Natural Media, NaturalFax, NaturalRecognition, NaturalText, Fusion, Open Telecommunications, Natural Platforms, NMS HearSay, AccessGate, MyCaller, and HMIC are trademarks or service marks of NMS Communications Corporation or its subsidiaries. Multi-Vendor Integration Protocol (MVIP) is a registered trademark of GO-MVIP, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. Windows NT, MS-DOS, MS Word, Windows 2000, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Clarent and Clarent ThroughPacket are trademarks of Clarent Corporation. Sun, Sun Microsystems, Solaris, Netra, and the Sun logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the United States and/or other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. Linux is a registered trademark of Linus Torvalds. Red Hat is a registered trademark of Red Hat, Inc. All other marks referenced herein are trademarks or service marks of the respective owner(s) of such marks. All other products used as components within this product are the trademarks, service marks, registered trademarks, or registered service marks of their respective owners.

Every effort has been made to ensure the accuracy of this manual. However, due to the ongoing improvements and revisions to our products, NMS Communications cannot guarantee the accuracy of the printed material after the date of publication or accept responsibility for errors or omissions. Revised manuals and update sheets may be published when deemed necessary by NMS Communications.

P/N 9000-62471-10

Revision history

Revision Release date Notes

1.0 March 2005 SRG, Video Access 1.0

Last modified: February 25, 2005

Refer to www.nmscommunications.com for product updates and for information about support policies, warranty information, and service offerings.

NMS Communications 3

Table Of Contents

Chapter 1: Introduction .................................................................................5

Chapter 2: Overview of the H.324M Interface................................................7 NMS Video Access overview .......................................................................... 7

Standards ............................................................................................... 9 H.324M Interface overview ..........................................................................10

MUX and demux capabilities......................................................................12 Audio and video formats...........................................................................12 CG board port densities ............................................................................13

Chapter 3: Developing applications..............................................................15 Configuring the board .................................................................................15 Designing host applications..........................................................................17 Defining the H.324M Interface configuration...................................................19

Pass-through configuration .......................................................................19 Audio transcoding configuration.................................................................20

Setting up the H.324M Middleware................................................................21 Setting up calls and media channels..............................................................21

Creating an endpoint................................................................................22 Creating a channel...................................................................................23 Connecting endpoints and channels............................................................24

Setting up and monitoring terminal capabilities...............................................25 Monitoring calls and sending messages to remote terminals .............................26 Handling errors ..........................................................................................26 Stopping the call and session .......................................................................26

Chapter 4: H.324M Middleware function summary.......................................27 Set up functions.........................................................................................27 Terminal capabilities functions......................................................................27 Call control and message functions ...............................................................28 Error handling functions ..............................................................................28 Shut down functions ...................................................................................28

Chapter 5: H.324M Middleware function reference ......................................29 Using the function reference ........................................................................29 h324_h223SkewIndication...........................................................................30 h324CloseChannel......................................................................................31 h324DefineMediaChannel ............................................................................32 h324Delete ...............................................................................................33 h324EndSession.........................................................................................34 h324FormatEvent.......................................................................................35 h324GetTermCaps......................................................................................36 h324Initialize.............................................................................................38 h324LineErrorReporting ..............................................................................39 h324OLCResponse......................................................................................42 h324RoundTripDelay ..................................................................................43 h324SetTermCaps......................................................................................44 h324SetTrace ............................................................................................46 h324SetupCall ...........................................................................................49 h324SetupMedia ........................................................................................50

Table of Contents H.324M Interface Manual


h324Start .................................................................................................51 h324Stop..................................................................................................53 h324SubmitEvent.......................................................................................54 h324UserIndication ....................................................................................56 h324VendorIDIndication..............................................................................58 h324VideoFastUpdate .................................................................................60 h324VideoTemporalSpatialTradeoff ...............................................................61

Chapter 6: H.324M Middleware call flow......................................................63 Call states .................................................................................................63

Begin state .............................................................................................65 Created state..........................................................................................65 BeginCallSetup state................................................................................66 CallSetup state........................................................................................66 BeginMediaSetup state .............................................................................67 MediaSetup State ....................................................................................68 EndSession state .....................................................................................68 End state ...............................................................................................68

Call flow components ..................................................................................69 Master slave determination .......................................................................69 Terminal capabilities set ...........................................................................70 Multiplex table entry ................................................................................72 Audio open logical channel........................................................................73 Video open logical channel ........................................................................74

Call flow examples......................................................................................75

Chapter 7: Errors, events, structures, and reason codes..............................79 Alphabetical error summary .........................................................................79 Numerical error summary............................................................................80 Events ......................................................................................................81 MSPP video structures.................................................................................84

Structures for creating MSPP endpoints.......................................................84 Structures for creating MSPP channels ........................................................87

H.324M Middleware structures .....................................................................88 H324_H223_SKEW_INDICATION ...............................................................88 H324_LCD..............................................................................................88 H324_START_PARAMS .............................................................................88 H324_TERM_CAPS...................................................................................89 H324_USER_INPUT_INDICATION...............................................................89 H324_VENDORID_INDICATION .................................................................90 H324_VIDEOTEMPORALSPATIALTRADEOFF_INDICATION ..............................90

Reason codes ............................................................................................91

Chapter 8: Glossary .....................................................................................93


11 Introduction This manual describes how to use the H.324M Interface to interact with 3G-324M terminals capable of audio and video, and provides descriptions of the H.324M Interface capabilities and functions. The H.324M Interface provides a flexible API to bridge 3G-324M clients into an IP network for access to various enhanced services applications. The H.324M Interface allows for simple and flexible call setup to the 3G-324M terminals on one side of the interface while providing control for IP media endpoints on the other side.

This manual targets video application developers who are using Natural Access. This document defines telephony terms where applicable, but assumes that you are familiar with the 3G-324M standard, telephony concepts, switching, Natural Access, and the C programming language.


22 Overview of the H.324M Interface

NMS Video Access overview

NMS Video Access enables customers to develop and deploy carrier grade applications for video communication solutions. Video Access components have a modular architecture. Components can be used independently or in conjunction with other Video Access components. Use components to build network systems such as video gateways and enhanced services platforms that support video applications.

Note: A software license is required to enable Video Access. Refer to the va_readme.txt file for information on obtaining and deploying a Video Access license.

NMS Video Access is a toolkit that contains the following components:

Component Description

H.324M Interface Enables video gateway functions or applications to establish connections with 3G-324M capable wireless terminals using H.245 messaging and H.223 multiplexing using the Natural Access MSPP service. The H.324M Interface allows applications to bridge 3G-324M connections to the IP network with optional audio transcoding.

Video Messaging Server Interface

Controls play, record, and storage, in 3GP file format, for audio and video data. An application accesses multimedia play and record functions through the Natural Access ADI service. For information, refer to the Video Messaging Server Interface Developer's Reference Manual, the ADI Service Developer's Reference Manual, and the MSPP Service Developer's Reference Manual.

Video Access also provides a demonstration program for creating a video mail application. For information, refer to the Video Mail Application Demonstration Program Manual.

A video transcoder (available separately) controls real-time media adaptation between two IP sources. The video transcoder enables video applications to control transcoding channels in video transcoding platforms (VTPs). For information, refer to the Video Transcoder Installation and Developer's Reference Manual. The video transcoder is available from NMS as a separate package. For more information, contact your NMS sales representative.

Video Access runs on NMS CG boards in the NMS Natural Access environment. For information, refer to the Natural Access manuals on the NMS web site.

Overview of the H.324M Interface H.324M Interface Manual


The following illustration shows the relationships of the Video Access components with the optional video transcoder:

Mobileswitching

center

Video mobile gateway

3G-324MInterface(H.223)

Media server

Contentformattingrecordingplayback

Media adaptation

Videotranscoding

Video appl icat ion

Video MessagingServer Interface

Transcoder resourcecontro l ler modu le

H.324M Interface(H.245)

Natura l Access

Control and media

Media

Control

Control

Control Media

H.324M Interface Manual Overview of the H.324M Interface


Standards

Video Access complies with the versions of the following standards:

Standard Version

3G-324M 3GPP TS 26.110 and 26.111, version 5.0.0, 2002

H.223 ITU-T, 2001

H.245 ITU-T, version 6, 2000

AMR 3GPP TS 26.090, 26.101, and 26.073, version 5.3.0, 2004

G.723.1 ITU-T, 1996

H.263 ITU-T, 1998

MPEG-4 ISO/IEC 14496-2, 2004

RTP RFC 3550 and 3551, 2003

H.263 over RTP RFC 2190, 1997

DTMF over RTP RFC 2833, 2000

MPEG-4 over RTP RFC 3016, 2000

AMR over RTP RFC 3267, 2002

3GP file format 3GPP TS 26.244, version 5.2.0, 2004



H.324M Interface overview

The H.324M Interface provides a media gateway between a PLMN (Public Land Mobile Network) or PSTN and an IP network, under the full control of the application.

On the PLMN side, media streams (audio and video) and control information (H.245) are multiplexed through H.223 on TDM channels. On the IP side, the audio and video streams are transported on separate RTP streams. Applications control all activity through an API set where all functionality is executed on NMS CG boards. Non-media specific functions such as call control signaling, trunk monitoring, OAM, and others that are also performed on the same platform, are governed through separate interfaces that are part of Natural Access.

The H.324M Interface contains the logic for 3G-324M connections and the H.223 MUX (H.324M Middleware), control for the video and audio channels and endpoints, as well as relevant control for several Natural Access services.

To support a video call, the application must use the following:

Component Description

OAM Configures and manages the boards.

ISDN Example of call control signaling for a TDM channel.

Switching service Controls the board's TDM switching connections.

MSPP service Creates and controls board endpoints and channels. Once Video Access is installed, NMS Fusion supports video components.

H.324M Controls the H.223 MUX and H.245 stack. This component is not a Natural Access service.

An IP signaling component for IP call control is not included in the Video Access H.324M Interface.



The following illustration shows the internal architecture of the H.324M Interface:

Video

MUXendpoint

Audioover RTP

Audio RTP endpoint

Videoover RTP

Video RTP endpoint

Audio

Video channel(pass-through)

Audio channel(pass-through)

orwith transcoding

IP

TDM

CG board

Appl icat ion

Host dr ivers

Operat ing sys tem

Host

H.324M Middleware

Natura l Access

OAM ISDN serv iceMSPP serv ice Switch ing serv ice

H.245stack

control

A video processing path and an audio processing path are tied to the MUX endpoint that contains the H.223 multiplexing and demultiplexing functionality.

Video data stream is not transcoded in the H.324M Interface, but audio transcoding can be performed if required.

The H.324M Middleware abstracts the details of the H.245 call setup negotiations, and allows for simple and flexible call setup. It fully abstracts the H.245 stack control and H.223 MUX configuration.

The application uses the MSPP service to create and control media RTP endpoints and channels and to create the MUX endpoint.

To have audio and video flow through the H.324M Interface, the application must create the MUX, audio and video endpoints and channels, connect them together, and interact with another 3G-324M device through the H.324M Middleware to setup the H.245 session.



This manual describes the H.324M Interface and the video-related MSPP commands and events passed between CG boards and gateway host applications. For basic gateway information, refer to the Fusion Developer's Manual and the MSPP Service Developer's Reference Manual.

MUX and demux capabilities

The MUX and demux (DPF) data processing function on DSP implements a selective subset of the functional capabilities enumerated in the ITU H.223 specification and H.324 specification for CCSRL/NSRP.

The following table summarizes the multiplexer supported features:

Specification Features Supported Not supported

Multiplexer x

AL1 protocol x

AL2 protocol x

H.223

AL3 protocol (no re-transmission) x

H.223 Annex A Multiplexer doubleflag Mode x

H.223 Annex B Golay coding for multiplexer header stuffing

PM synchronization

x

H.223 Annex C Additional error reduction capabilities x

H.223 Annex D Additional error reduction capabilities x

H.324 Annex A, Annex C CCSRL/NSRP x

Audio and video formats

A single audio and video codec is selected and enabled for the duration of the video call.

The following table presents the audio and video formats that are supported on both sides of the gateway:

Type Format

TDM audio AMR-NB G.723-1

TDM video ITU-T H.263 Baseline level 10 ISO/IEC 14496-2 MPEG-4 simple profile level 0

IP audio AMR-NB over RFC 3267 G.723-1 G.711

IP video H.263 Baseline level 10 over RFC 2190 MPEG-4 simple profile level 0 over RFC 3016



The H.324M Interface supports the pass-through (no transcoding) of the following codecs:

• AMR narrow band audio, 3GP version 5.3, RFC 3267 compliant for RTP payload format

• G.723.1 audio

• MPEG-4 simple profile level 0 video, RFC 3016 compliant for RTP payload

• H.263 baseline video, as specified in annex X (level 10), RFC 2190 compliant for RTP packetization, with exception of Tx support in mode B.

Pass-through means that, from PSTN to IP network, encoded frames are H.223 demultiplexed, encapsulated in RTP-packets and sent on the IP interface. No transcoding is performed on the frame payload.

For the reverse direction (from IP to PSTN), a jitter buffer function is provided on both audio and video streams.

When receiving AMR NB codec from the TDM interface, the audio logical channel of the H.223 MUX can optionally be transcoded to G.711 for transmission over IP.

Note: The application can convert AMR audio to codecs other than RTP G.711, at the expense of port density. Refer to CG board port densities on page 13 for more information. Refer to the Fusion Developer's Manual for a list of supported audio codecs on IP.

CG board port densities

The H.324M Interface can control one or more CG boards. The following table presents the port density performance numbers for the supported CG boards:

Description /3200 MIPS /6400 MIPS /9600 MIPS

Pass-through 120 120 120 CG 6500C

With audio transcoder 48 96 120

Pass-through 48 Not applicable. Not applicable. CG 6000 and CG 6000C

With audio transcoder 48 Not applicable. Not applicable.

Note: Host CPU calculations are not considered in the previous table.

Running the board with an audio transcoder allows AMR channels to be converted to G.711.

The port density performance numbers in the previous table do not apply and must be recalculated if:

• A codec other than G.711 is used.

• The board is used simultaneously for multiple functions (for example, running the H.324M Interface and the Video Messaging Server Interface). Refer to the Video Mail Application Demonstration Program Manual for an example.


33 Developing applications Configuring the board

Refer to the CG board installation and developer's manual for general information about configuring the board.

When configuring a CG board for a video application, you must configure MUX DSP pools. The following example file shows how to configure a CG board with a maximum number of 48 ports for a video mail application. The video-specific settings are in bold. ################################################################ # VIDEO_MAIL.CFG # # CG 6000 Boot configuration file for Video Mail System # # ################################################################ ################################################################ # CG 6000 IP Address, subnet mask, and gateway IP address. # Note: the IP configuration below is for a Ethernet Failover # THIS CONFIGURATION FILE WILL FAIL UNLESS THE VARIABLE STRINGS # BELOW ARE REPLACED WITH REAL IP ADDRESSES. IPC.AddRoute[0].DestinationAddress = 10.118.7.100 IPC.AddRoute[0].Mask = 255.255.0.0 IPC.AddRoute[0].Interface = 1 #IPC.AddRoute[1].DestinationAddress = 0.0.0.0 #IPC.AddRoute[1].Mask = 0.0.0.0 #IPC.AddRoute[1].GatewayAddress = 10.1.0.1 ################################################################ ################################################################ # E1 SPECIFICS TCPFiles = nocc isd0 NetworkInterface.T1E1[0..3].Type = E1 NetworkInterface.T1E1[0..3].Impedance = G703_120_OHM NetworkInterface.T1E1[0..3].LineCode = HDB3 NetworkInterface.T1E1[0..3].FrameType = CEPT NetworkInterface.T1E1[0..3].SignalingType = PRI NetworkInterface.T1E1[0..3].D_Channel = ISDN NetworkInterface.T1E1[0..3].CRCMFmode = C44OFF DSPStream.VoiceIdleCode[0..3] = 0xD5 DSPStream.SignalIdleCode[0..3] = 0xB MaxChannels = 250 ################################################################ ################################################################ # CLOCK SETTINGS Hdlc[0,3,6,9].Boot = YES Hdlc[0,3,6,9].Comet.TxTimeSlot = 16 Hdlc[0,3,6,9].Comet.RxTimeSlot = 16 Clocking.HBus.ClockMode = STANDALONE Clocking.HBus.ClockSource = NETWORK Clocking.HBus.ClockSourceNetwork = 1 ################################################################

Developing applications H.324M Interface Manual


################################################################ # DSP RELATED SETTINGS # # DPFs to load on each DSP # Bit compliant G.723 => f_g723 # Reduced MIPS G.723 => f_g723r # # Fusion supports the following vocoders (* denotes complex vocoder): # G.711 => f_g711 # G.723* => f_g723, f_g723r # G.729A* => f_g729a # G.726* => f_g726 # # Due to DSP memory constraints, all supported Fusion vocoders cannot be loaded # simultaneously on the same DSP. The line "DSP.C5x[1..31].Files" specifies # what DSP functions are loaded to the DSPs. If a complex vocoder is required # that is not specified in the default configuration, it may be added by # removing a complex vocoder, and putting the new vocoder in its place. # For example, to run G.726, f_g726 needs to replace one of the other complex # vocoders below (f_g723 or f_g729a). NOTE: Similar changes are required to the # "Resource[0].Definitions" string. # DSP.C5x[0].Files = qtsignal callp tone ptf dtmf echo mf DSP.C5x[1..31].DataReqTimeOffset = 7 DSP.C5x[0..31].XLaw = A_LAW DSP.C5x[1..12].XLaw = NO_LAW #Very important for 3G-324M configurations DSP.C5x[1..12].DataInQSize = 0x2D0 DSP.C5x[1..12].DspOutQStart = 0xFB50 DSP.C5x[1..12].DspOutQSize = 0x3A0 # DSP Libraries DSP.C5x[0..31].Libs = cg6kliba f_shared ################################################################ ################################################################ # RESOURCE MANAGEMENT # ################################################################ ################################################################ # Resource Pool 1 - Mux ################################################################ Resource[0].Name = RSC1 Resource[0].TCPs = nocc Resource[0].DSPs = 1 2 3 4 5 6 7 8 9 10 11 12 Resource[0].Size = 48 Resource[0].StartTimeSlot = 0 Resource[0].Definitions = (mux.mux & mux.demux) ################################################################ # DOWNLOADABLE RUNTIME MODULES DLMFiles[0] = cg6krun DLMFiles[1] = cg6kfusion DLMFiles[2] = isdnetsi ################################################################# ################################################################ # DEBUG STUFF DebugMask = 0x00 ##############################################################

H.324M Interface Manual Developing applications


Designing host applications

To setup the H.324M Interface, the application must do the following:

Step Action Using the following...

1 Create Natural Access contexts and event queues. Natural Access service

2 Create and connect MSPP endpoints and channels. Each 3G-324M port requires:

• 1 MUX endpoint

• 1 video channel and 1 audio channel

• 1 video RTP endpoint and 1 audio RTP endpoint

MSPP service

3 Make switching connections from the trunk to the MUX endpoint. Switching service

4 Set up TDM call control (ISDN, SS7). ISDN/SS7

5 Call H.324M functions to control the H.245 sessions. H.324M Interface

6 Wait for Natural Access events using ctaWaitEvent. Natural Access service

7 Submit all events received from Natural Access to h324SubmitEvent. h324SubmitEvent consumes some events and does not consume other events.

H.324M Interface

8 Process events that h324SubmitEvent does not consume including H.324 events that are generated by the H.324M Interface.

9 Free buffers for all MSPP events that include buffers, except for those consumed by h324SubmitEvent.

MSPP service

The application can choose between the following methods to create and connect the MSPP RTP endpoints and channels:

• Create and connect statically audio and video channels and endpoints at application initialization, as suggested in the previous table.

• Create and connect dynamically audio and video channels and endpoints on a per call base, after H.245 negotiation completes.

If audio transcoding is needed, additional endpoints (DS0 and RTP) and a transcoding MSPP channel is required. In this case, the application must choose the static method.

The application can use any supported NMS programming model (single-threaded programming, multi-threaded programming, or multi-process programming). All NMS-supplied APIs are fully thread-safe. For information about Natural Access programming models, refer to the Natural Access Developer's Reference Manual.



The following illustration shows the relationship between the application and the H.324M Interface:

MSPPservice NCC/ISDN

services

Natural Access

Application

CTAEVN_*MSPEVN_CREATE_*MSPEVN_DESTROY_*MSPEVN_ENABLE_*MSPEVN_DISABLE_*MSPEVN_CONNECT_DONEMSPEVN_DISCONNECT_DONEMSPEVN_QUERY_DONE, event.objHd != MSP_MUX_EPMSPEVN_SENDCOMMAND_DONE, event.objHd != MSP_MUX_EP

Context,endpoint, andchannel setup

Call control

Eventqueue

ISDNEVN_START_PROTOCOLISDNEVN_STOP_PROTOCOLNCCEVN_ACCEPTING_CALLNCCEVN_ANSWERING_CALLNCCEVN_CALL_CONNECTEDNCCEVN_CALL_DISCONNECTEDNCCEVN_CALL_PROCEEDINGNCCEVN_CALL_RELEASEDNCCEVN_INCOMING_CALLNCCEVN_PLACING_CALLNCCEVN_REJECTING_CALLNCCEVN_*

H324EVN_REMOTE_CAPABILITIESH324EVN_CALL_SETUP_DONEH324EVN_REMOTE_OLCH324EVN_MEDIA_SETUP_DONEetc.

H.324M control

h324Initializeh324Starth324GetTermCapsh324SetTermCapsh324SetupCallh324SetupMediah324OLCResponseh324DefineMediaChannelh324EndSessionh324Stoph324CloseChannel

ctaQueueEvent ( H324EVN_* )

mspCreatexxxmspConnectmspEnablexxxmspSendCommand (except to MUX EP)mspSendQuery (except to MUX EP)mspDisablexxxmspDisconnectmspDestroyxxx

All events notconsumed byh324SubmitEvent

Events consumed byh324SubmitEvent:MSPEVN_DPF_DEBUG_REPORTMSPEVN_MUX_GET_H245_MSGMSPEVN_MUX_PMSYNC_STOPPEDMSPEVN_MUX_PMSYNC_STARTEDMSPEVN_QUERY_DONE, event.objHd == MSP_MUX_EPMSPEVN_SENDCOMMAND_DONE, event.objHd == MSP_MUX_EP

Main event loop

Applicationevent

processing

isdnStartProtocolisdnStopProtocolnccStartProtocolnccPlaceCallnccRejectCallnccAcceptCallnccAnswerCallnccReleaseCallnccDisconnectCalletc.

h324SubmitEvent

H.324MInterface

ctaWaitEvent



Defining the H.324M Interface configuration

When receiving AMR NB codec, the audio logical channel of the H.223 MUX can optionally be transcoded to G.711 for transmission over IP.

The application must create the endpoints and channels on the board, based on the media codecs selected and audio transcoding requirement.

Pass-through configuration

The following illustration shows a pass-through configuration:

Jitter

Video

MUXendpoint

TDM

Jitter

Video RTP endpoint

Video pass-through channel

Audio pass-through channel

Video pass-through

Audio pass-through

Pass-through

Pass-through

Video

Audio

Audio RTPendpoint

IP

DSP component

Video-specific component

If no audio transcoding is required, the application must create the following for each 3G-324M port:

• A MUX/DEMUX endpoint, associated with a TDM timeslot

• A video pass-through channel and video endpoint (MPEG-4 or H.263)

• An audio pass-through channel and Fusion audio endpoint

The application must connect the video channel with the MUX endpoint and the video endpoint, and connect the audio channel with the MUX endpoint and the audio endpoint. Both pass-through channels must then be enabled.



Audio transcoding configuration

The following illustration shows an audio transcoding configuration:

Video

MUXendpoint

TDM

Jitter

Video RTP endpoint

Audio

Video pass-through channel

Video pass-through

Pass-through

Video

G.711

G.711 audioRTP endpoint

IP

Audio transcodingJitter

G.711 MSPP channelD

ecod

er

Enco

der

PCM

DSP component

Video-specific component

DS0 endpoint DS0 endpoint

Encoder

Decoder

AMR MSPP channel

Instead of configuring a pass-through audio channel and audio endpoint, the application can require G.711 RTP packetized audio on the IP side. In this case, the application must select AMR audio codec on the 3G-324M side, and must create an AMR MSPP channel connected with a G.711 MSPP channel through DS0 endpoints TDM switching.



Setting up the H.324M Middleware

The H.324M Middleware enables you to initialize and start the H.324M Middleware, H.245 stack, and MUX endpoint.

To... Use...

Set up the H.324M Middleware for use for the application, and specify the log file name

h324Initialize

Create an H.245 stack for the specified MUX, and start H.223 synchronization on a 3G-324M call base

h324Start

Setting up calls and media channels

The H.324M Middleware allows you to control H.245 session logic. Using functions and corresponding events, the application must ensure that:

• Master/slave determination and terminal capability exchange procedures are properly completed

• Inbound and outbound uni-directional audio logical channels are opened

• A bi-directional video logical channel is opened

To... Use...

Inform the H.324M Middleware that it can begin terminal capability exchange and master slave determination

h324SetupCall

Inform the H.324M Middleware that open logical channel and MUX table exchange procedures can begin (after the setup call procedures have completed)

h324SetupMedia

Define a media channel (audio or video) for the purpose of sending out an open logical channel (OLC), and initiate the OLC transfer

h324DefineMediaChannel

Inform the H.324M Middleware if it should accept or reject an open logical channel request (audio or video) offered by the remote terminal

h324OLCResponse



Creating an endpoint

The H.324M Interface provides video-specific MSPP endpoints (indicated in bold in the following table). The corresponding identifiers are used in the eEpType field in the MSP_ENDPOINT_ADDR structure and in the eParmType field in the MSP_ENDPOINT_PARAMETER structure.

Endpoint type Identifier Initialization structure

MPEG-4 formatted video

MSP_ENDPOINT_RTPFDX_VIDEO_MPEG4 RTPRTCP_ENDPOINT_ADDR RTPRTCP_ENDPOINT_PARMS

H.263 formatted video

MSP_ENDPOINT_RTPFDX_VIDEO_H263 RTPRTCP_ENDPOINT_ADDR RTPRTCP_ENDPOINT_PARMS

G.723 audio (used for G.723 bypass)

MSP_ENDPOINT_RTPFDX RTPRTCP_ENDPOINT_ADDR RTPRTCP_ENDPOINT_PARMS

AMR audio (used for AMR bypass)


G.711 audio (G.711 endpoint used for AMR transcoding)


DS0 (used for AMR transcoding)

MSP_ENDPOINT_DS0 DS0_ENDPOINT_ADDR DS0_ENDPOINT_PARMS

H.223 MUX/demux

MSP_ENDPOINT_MUX MUX_ENDPOINT_ADDR

For more information, refer to the MSPP Service Developer's Reference Manual.

Refer to RTPRTCP_ENDPOINT_ADDR, RTPRTCP_ENDPOINT_PARMS, and MUX_ENDPOINT_ADDR for video specific information.

The following example shows how to declare that an endpoint is a MUX endpoint and how to set its timeslot: GwConfig[i].MuxEp.Addr.eEpType = MSP_ENDPOINT_MUX; GwConfig[i].MuxEp.Addr.EP.Mux.nTimeslot = 5; GwConfig[i].MuxEp.Param.eParmType = MSP_ENDPOINT_MUX;

All endpoints are created using mspCreateEndpoint. For example: ret = mspCreateEndpoint(GwConfig[i].MuxEp.ctahd, &GwConfig[i].MuxEp.Addr, &GwConfig[i].MuxEp.Param, &GwConfig[i].MuxEp.hd);



Creating a channel

The H.324M Interface provides video-specific MSPP channels (indicated in bold in the following table). The corresponding identifiers are used in the channelType field in the MSP_CHANNEL_ADDR structure and in the channelType field in the MSP_CHANNEL_PARAMETER structure.

Channel type Identifier Initialization structure

Video MPEG-4 MGVideoChannel MSP_CHANNEL_ADDR MSP_VIDEO_CHANNEL_PARMS

Video H.263 MGH263VideoChannel MSP_CHANNEL_ADDR MSP_VIDEO_CHANNEL_PARMS

G.723 bypass MGG723BypassChannel MSP_CHANNEL_ADDR MSP_VOICE_CHANNEL_PARMS

AMR bypass MGAMRBypassChannel MSP_CHANNEL_ADDR MSP_VOICE_CHANNEL_PARMS

AMR channel (for AMR transcoding) MGAMRChannel MSP_CHANNEL_ADDR MSP_AUDIO_CHANNEL_PARMS

G.711 channel (for AMR transcoding)

G711FullDuplex MSP_CHANNEL_ADDR MSP_VOICE_CHANNEL_PARMS

For more information, refer to MSP_VIDEO_CHANNEL_PARMS and MSP_AUDIO_CHANNEL_PARMS.

For information about other structures referenced in the previous table, refer to the MSPP Service Developer's Reference Manual.

The following example shows how to create a channel: GwConfig[i].VidChan.Addr.channelType = MGVideoChannel; GwConfig[i].VidChan.Param.channelType = MGVideoChannel;

All channels are created using mspCreateChannel. For example: ret = mspCreateChannel( GwConfig[i].VidChan.ctahd, &GwConfig[i].VidChan.Addr, &GwConfig[i].VidChan.Param, &GwConfig[i].VidChan.hd);



Connecting endpoints and channels

Endpoints and channels are connected using mspConnect as follows: mspConnect ( EP1 handle, channel handle, EP2 handle)

For video-specific endpoints, the order of the endpoints in mspConnect is important. The following table shows the order for the different channel connections:

Channel type

Endpoint 1 Channel Endpoint 2

MPEG-4 video channel

MSP_ENDPOINT_RTPFDX_VIDEO_MPEG4 MGVideoChannel MSP_ENDPOINT_MUX

H.263 video channel

MSP_ENDPOINT_RTPFDX_VIDEO_H263 MGH263VideoChannel MSP_ENDPOINT_MUX

G.723 bypass channel

MSP_ENDPOINT_RTPFDX MGG723BypassChannel MSP_ENDPOINT_MUX

AMR bypass channel

MSP_ENDPOINT_RTPFDX MGAMRBypassChannel MSP_ENDPOINT_MUX

AMR portion of the audio transcoding path

MSP_ENDPOINT_DS0 MGAMRChannel MSP_ENDPOINT_MUX

For example: ret = mspConnect( GwConfig[i].VidRtpEp.hd, GwConfig[i].VidChan.hd, GwConfig[i].MuxEp.hd);

MUX endpoint unsolicited events

The typedefs for the structures defining the unsolicited events from the MUX endpoint are of the following form: typedef struct { DWORD filter_id; // Filter ID (subtype) added by MSPP service WORD evn_base; // 001b WORD evn_id; // 23xx WORD ccc; // event payload word 1 WORD ddd; // event payload word 2 . . . } msp_MUX_XXX;

The corresponding MSPP event ID field is MSPEVN_MUX_XXX, and is contained in the CTAccess ID field of the Natural Access event.

The msp_MUX_XXX structure data is contained in the buffer attached to the Natural Access event.

MUX unsolicited events do not need to be interpreted by the application because the MUX unsolicited events are consumed by the H.324M Middleware. For more information, refer to h324SubmitEvent.



Commands and queries

The following commands and queries can be sent to the MPEG-4 and H.263 full-duplex RTP endpoints:

Commands and queries (msp command structure)

Description

MSP_CMD_RTPFDX_CONFIG (msp_ENDPOINT_RTPFDX_CONFIG)

Configuration parameters for the endpoint.

MSP_CMD_RTPFDX_MAP (msp_ENDPOINT_RTPFDX_MAP)

Value that assigns a payload ID to a vocoder.

MSP_CMD_RTPFDX_LINK_EVENTS (msp_ENDPOINT_RTPFDX_LINK_EVENTS)

Value that enables or disables reporting of link availability transitions through unsolicited events.

MSP_QRY_RTPFDX_STATUS (msp_ENDPOINT_RTPFDX_STATUS)

Returns information about the RTP endpoint filter state.

MSP_CMD_RTPFDX_RTCP_EVENTS (msp_ENDPOINT_RTPFDX_RTCP_EVENTS)

Value that enables or disables reporting of RTCP events through unsolicited events.

The following commands and queries can be sent to the video channel jitter buffer filters:

Commands and queries (msp command structure)

Description

MSP_QRY_JITTER_VIDEO_GET_STATE (msp_FILTER_JITTER_VIDEO_STATE)

Obtains the status of the video jitter buffer.

Setting up and monitoring terminal capabilities

The H.324M Middleware enables you to establish terminal capabilities settings on local and remote terminals.

To... Use...

Query the H.324M Middleware for the H.324M Interface or remote terminal 3G-324M audio, video and multiplexing capabilities

h324GetTermCaps

Set the local terminal capabilities and to initiate the transfer of the terminal capabilities (H.245 TCS exchange)

h324SetTermCaps



Monitoring calls and sending messages to remote terminals

The H.324M Middleware enables you to send control messages to the remote terminal and to submit incoming messages to the H.324M Middleware.

To... Use...

Submit Natural Access events to the H.324M Middleware h324SubmitEvent

Send a user indication to the terminal (This assumes proprietary interpretation of such messages by the remote terminal.)

h324UserIndication

Send a VideoTemporalSpatialTradeoff message to the remote terminal

h324VideoTemporalSpatialTradeoff

Send a video fast update message to the remote terminal to request the terminal to generate a complete intra-coded picture

h324VideoFastUpdate

Send an H.223 skew indication to the terminal to advertise any known skew between audio and video media streams sent by the H.324 Interface on the TDM side

h324_h223SkewIndication

Send a VendorID indication to the terminal. The application can build a vendor indication identifier.

h324VendorIDIndication

Send a round trip delay to the remote terminal h324RoundTripDelay

Format an H.324M event into a string for print diagnostics h324FormatEvent

Handling errors

To... Use...

Define the level of tracing for the H.324M library h324SetTrace

Turn on error reporting statistics in the H.223 demultiplexer. Use these statistics to determine the quality of the inbound radio link from the H.324 terminal to the demultiplexer.

h324LineErrorReporting

Stopping the call and session

The following functions are provided to tear down channels and sessions:

To... Use...

Close an existing media channel (audio or video) h324CloseChannel

Inform the H.324M Middleware to terminate the current H.324 session, by sending an EndSession message to the remote terminal

h324EndSession

Stop the H.324M Middleware for the specified MUX. This function must be called at the end of an H.324 call.

h324Stop

Cleanly release any objects and memory associated with an instance of the H.324M Middleware

h324Delete


44 H.324M Middleware function summary

Set up functions

Use the following functions to set up the H.324M Middleware and to set up calls and media channels:

Function Description

h324DefineMediaChannel Defines a media channel to send out an open logical channel (OLC), and initiate the OLC transfer.

h324Initialize Sets up the H.324M Middleware for use.

h324OLCResponse Lets the H.324M Middleware know whether to accept or reject an open logical channel (OLC) offered by the remote terminal.

h324SetupCall Informs the H.324M Middleware that it can begin terminal capability exchange and master slave determination.

h324SetupMedia Tells the H.324M Middleware that open logical channel (OLC) and MUX table exchange can begin.

h324Start Creates an H.245 stack for the specified MUX and sets the initial values that are needed to begin an exchange with the client.

For more information, refer to Setting up the H.324M Middleware on page 21 and Setting up calls and media channels on page 21.

Terminal capabilities functions

Use the following functions to set up and monitor terminal capabilities in the H.324M Middleware:


h324GetTermCaps Queries the service for the terminal capabilities listed for the terminal.

h324SetTermCaps Sets the local terminal capabilities for the terminal and initiates the transfer of the terminal capabilities set.

For more information, refer to Setting up and monitoring terminal capabilities on page 25.

H.324M Middleware function summary H.324M Interface Manual


Call control and message functions

Use the following functions to monitor calls and send messages to the remote terminal:


h324_h223SkewIndication Sends an H.223 skew indication to the terminal.

h324FormatEvent Formats an H.324M event into a string for print diagnostics.

h324RoundTripDelay Sends a round trip delay to the remote terminal.

h324SubmitEvent Submits H.324M events from the event queue to the H.324M Middleware.

h324UserIndication Sends a user indication to the terminal.

h324VendorIDIndication Sends a vendor ID indication to the remote terminal.

h324VideoFastUpdate Sends a video fast update message to the remote terminal.

h324VideoTemporalSpatialTradeoff Sends a VideoTemporalSpatialTradeoff message to the remote terminal.

For more information, refer to Monitoring calls and sending messages to remote terminals on page 26.

Error handling functions

Use the following functions to manage errors in the H.324M Middleware:


h324LineErrorReporting Turns on error reporting statistics in the MUX endpoint.

h324SetTrace Defines the level of tracing for the H.324M Middleware.

For more information, refer to Handling errors on page 26.

Shut down functions

Use the following functions to stop a call or session in the H.324M Middleware:


h324CloseChannel Closes an existing media channel.

h324Delete Releases any objects and memory associated with an instance of the H.324M Middleware.

h324EndSession Informs the H.324M Middleware to terminate the current H.324 session at the end of the call.

h324Stop Stops the H.324M Middleware for the specified MUX.

For more information, refer to Stopping the call and session on page 26.


55 H.324M Middleware function reference

Using the function reference

This section provides an alphabetical reference to the H.324M Middleware functions.

All functions in the H.324M Middleware share common features. All functions are of type DWORD, and return a value that represents the success or failure of the call. Success is #defined equal to SUCCESS (0). Other possible return values are listed in the description of each individual call.

All functions except h324Initialize are passed an MSPHD that is the handle to a MUX endpoint. This handle is returned to the application by the MSPP service when the MUX endpoint is created. This handle is used to determine the H.324M Middleware’s context (in other words, to determine with which channel a command or event is associated).

The H.324M Middleware is asynchronous. No H.324M Middleware functions will block while waiting for a response from the CG board or from the remote 3G-324M video terminal. Any information from the CG board or the remote 3G-324M video terminal will be sent to the application using its Natural Access event queue.

The example code presented in the function descriptions are excerpts from the vmsamp demonstration program. Refer to the Video Mail Application Demonstration Program Manual for more information.

H.324M Middleware function reference H.324M Interface Manual


h324_h223SkewIndication

Sends an H.223 skew indication to the terminal.

Prototype

DWORD h324_h223SkewIndication ( MSPHD msphd, unsigned int skewInMs, channelSkewType skewType)

Argument Description

msphd MSPP handle associated with the MUX.

skewInMs Milliseconds of audio or video skew to indicate to the terminal.

skewType Channel skew type of either audioLate or videoLate:

typedef enum { audioLate = 0, // Video must be delayed to align with late audio.videoLate // Audio must be delayed to align with late video.} channelSkewType;

Return values

Return value Description

SUCCESS

CTAERR_NOT_FOUND msphd was not found. Either h324Start was not called or h324Delete has been called.

H324ERR_INTERNAL_ERROR Internal error in H.324M Middleware.

H324ERR_MUTEX_LOCK_FAILED Internal error trying to lock mutex.

H324ERR_NOT_INITIALIZED h324Initialize was not called first.

Events

None.

Example rc = h324_h223SkewIndication(GwConfig[0].MuxEp.hd, skewInMs, (selection == 'a') ? audioLate : videoLate); if (rc == SUCCESS) printf("The SkewIndication message was sent successfully.\n"); else printf("Failed to send the SkewIndication message...\n");

H.324M Interface Manual H.324M Middleware function reference


h324CloseChannel

Closes an existing media channel.

Prototype

DWORD h324CloseChannel ( MSPHD msphd, DWORD channel)



channel Defines which of the following channels to close:

H324RSN_AUDIO_IN H324RSN_AUDIO_OUT H324RSN_VIDEO

Return values


SUCCESS





Events

Event Description

H324EVN_CHANNEL_CLOSED Local or remote terminal successfully closes a channel. The size field defines which channel closed.

Example ret = h324CloseChannel( GwConfig[nGw].MuxEp.hd, H324RSN_VIDEO ); if( ret != SUCCESS ) { printf("Failed to close the video logical channel...\n"); return ret; } ret = WaitForSpecificEvent( nGw, GwConfig[nGw].hCtaQueueHd, H324EVN_CHANNEL_CLOSED, &event );




Defines a media channel to send out an open logical channel (OLC), and initiate the OLC transfer, if h324SetupMedia has already been sent, and H324EVN_CALL_SETUP_DONE has been received.

Prototype

DWORD h324DefineMediaChannel ( MSPHD msphd, H324_MEDIA_CAPABILITY *mediaCapOut, H324_MEDIA_CAPABILITY *mediaCapIn)



mediaCapOut Pointer to the structure that sets up the details of a media capability for the outbound channel.

mediaCapIn Pointer to the structure that sets up the details of a media capability for the inbound channel (or NULL for unidirectional channels).

Return values


SUCCESS





Events

None.

Details

h324DefineMediaChannel provides the H.324M Middleware with the full definition of a video channel, which was not known when the terminal capabilities were defined.

Example printf("Calling h324DefineMediaChannel for Out Audio OLC with Audio codec %d\n", pCfg->localTermCaps.capTable[0].choice); ret = h324DefineMediaChannel( pCfg->MuxEp.hd, &pCfg->localTermCaps.capTable[0], 0 ); if(ret != SUCCESS) { printf("Error: h324DefineMediaChannel for audio returned 0x%08x\n",ret); return ret; }



h324Delete

Releases any objects and memory associated with an instance of the H.324M Middleware. h324Delete must be called after H324EVN_STOP_DONE is received.

Prototype

DWORD h324Delete ( MSPHD msphd)



Return values


SUCCESS





Events

None.

Example case H324EVN_STOP_DONE: printf("H324EVN_STOP_DONE received - Delete the H324M instance now\n"); ret = h324Delete(pCfg->MuxEp.hd); if(ret != SUCCESS) { printf("h324Delete returned 0x%08x\n",ret); return ret; }



h324EndSession

Informs the H.324M Middleware to terminate the current H.324 session at the end of the call.

Prototype

DWORD h324EndSession ( MSPHD msphd)



Return values


SUCCESS





Events

Event Description

H324EVN_END_SESSION_DONE End session message was delivered to the remote terminal.

Example ret = h324EndSession( pCfg->MuxEp.hd ); if(ret != SUCCESS) { printf("h324EndSession returned 0x%08x\n",ret); return ret; } ret = WaitForSpecificEvent( nGw, GwConfig[nGw].hCtaQueueHd, H324EVN_END_SESSION_DONE, &event ); if ( ret != 0 ) { printf(“h324EndSession failed to get remote ACK\n"); return ret; }



h324FormatEvent

Formats an H.324M event into a string for print diagnostics.

Prototype

DWORD h324FormatEvent ( char *lineprefix, CTA_EVENT *event, char *buffer, unsigned size)


lineprefix Pointer to a character string that is placed at the beginning of every new line in the formatted event string.

event Pointer to an event structure to be formatted. The CTA_EVENT structure is:

typedef struct { DWORD id; /* Event code and source service ID */ CTAHD ctahd; /* Natural Access context handle */ DWORD timestamp; /* Timestamp */ DWORD userid; /* Userid (defined by ctaCreateContext) */ DWORD size; /* Size of buffer if buffer != NULL */ void *buffer; /* Buffer pointer */ DWORD value; /* Event status or event-specific data */ DWORD objHD; /* Service object handle */ } CTA_EVENT;

buffer Pointer to the buffer to receive the event string.

size Size of the buffer in bytes.

Return values


SUCCESS

Events

None.

Details

h324FormatEvent creates a detailed textual description of the H.324M event.

See also

h324SubmitEvent

Example void DemoShowEvent( CTA_EVENT *event ) { char format_buffer[CTA_MAX_FORMAT_SIZE]; char *prefix = "\t\t\t"; /* default demo indent */ format_buffer[0] = '\0'; h324FormatEvent( prefix, event, format_buffer, CTA_MAX_FORMAT_SIZE ); printf( "%s", format_buffer ); }



h324GetTermCaps

Queries the service for the terminal capabilities listed for the terminal.

Prototype

DWORD h324GetTermCaps ( MSPHD msphd, WORD location, H324_TERM_CAPS *termCaps)



location H324_LOCAL_TERMINAL = Local terminal capabilities. H324_REMOTE_TERMINAL = Remote terminal capabilities.

termCaps Pointer to the terminal capabilities structure returned for the local or remote terminal:

typedef struct tag_MULTIPLEX_CAPABILITY { BOOL dataWithAL1; BOOL audioWithAL2; BOOL videoWithAL2; BOOL videoWithAL3; WORD maximumAL1MPDUSize; WORD maximumAL2MSDUSize; WORD maximumAL3MSDUSize; #ifdef EXTENDED_CAPS BOOL videoWithAL1; BOOL audioWithAL1; BOOL audioWithAL3; BOOL dataWithAL2; BOOL dataWithAL3; BOOL alpduInterleaving; BOOL rsCodeCapability; #endif } MULTIPLEX_CAPABILITY; typedef union tag_MEDIA_UNION{ MMP4VIDEOOPTIONS mpeg4; MH263OPTIONS h263; MH261OPTIONS h261; MG711OPTIONS g711; MG7231OPTIONS g723; MGSMAMROPTIONS gsmamr; } MEDIA_UNION; typedef struct tag_MEDIA_CAPABILITY { BOOL bReceive; BOOL bTransmit; int index; DWORD choice; #define H324_MPEG4_VIDEO 0 #define H324_H263_VIDEO 1 #define H324_H261_VIDEO 2 #define H324_G711_AUDIO 3 #define H324_G723_AUDIO 4 #define H324_AMR_AUDIO 5 DWORD size; MEDIA_UNION u; } H324_MEDIA_CAPABILITY; typedef struct tag_H324_TERM_CAPS{ DWORD size; MULTIPLEX_CAPABILITY muxCap; DWORD wCapCount; // Number of caps H324_MEDIA_CAPABILITY capTable[16]; } H324_TERM_CAPS;



Return values


SUCCESS





Events

None.

Details

If no terminal capabilities have been set by the application, the default terminal capabilities are returned. Use h324GetTermCaps to set up the outgoing terminal capabilities set and to retrieve the incoming terminal capabilities set.

For the outbound terminal capabilities set, use h324GetTermCaps to retrieve the default set of terminal capabilities structures based on the list of capabilities defined in the start parameters structure or based on a default list of AMR and MPEG-4, if no start parameters were provided. You then edit specific parameters in these structures as required, and pass them back to the H.324M Middleware using h324SetTermCaps.

For the inbound terminal capabilities set, you can retrieve a copy of the set at any time after receiving the H324EVN_REMOTE_CAPS event.

Example ret = h324GetTermCaps( pCfg->MuxEp.hd, H324_REMOTE_TERMINAL, &remoteTermCaps); if ( ret != SUCCESS) { printf("h324GetTermCaps. Return code is %x\n", ret); return ret; } printf("Call to Remote h324GetTermCaps returned %d capabilities\n", remoteTermCaps.wCapCount );



h324Initialize

Sets up the H.324M Middleware for use. This function must be called only once by the application, and must not be called by more than one thread.

Prototype

DWORD h324Initialize (char *logFileName)


logFileName H.324 log file name. If NULL, the default file name of h324.log is used.

Return values


SUCCESS

H324ERR_ALREADY_INITIALIZED h324Initialize has already been called.

H324ERR_LOG_FILE_OPEN_FAILED Error opening the log file.

H324ERR_MUTEX_CREATE_FAILED Failed to create mutex semaphore.

Events

None.

Example ret = h324Initialize(gwParm.sH324LogFile); if ( ret != SUCCESS) { printf("h324Initialize . Return code is %x\n", ret); exit(1); }



h324LineErrorReporting

Turns on error reporting statistics in the H.223 demultiplexer. Use the statistics to determine the quality of the inbound radio link from the H.324 terminal to the demultiplexer.

Prototype

DWORD h324LineErrorReporting ( MSPHD msphd, DWORD command, WORD param1, WORD param2)



command

Valid values are:

Value Description

H324_LINE_STAT_CMD_ERROR_EVENT Sends an error event when the specified error is detected.

H324_LINE_STAT_CMD_PERIODIC Periodically reports line error counts.

H324_LINE_STAT_CMD_RESET_STAT Resets all line error counts to zero.

param1

The param1 value depends upon the value selected for command:

If command is... The param1 value...

H324_LINE_STAT_CMD_ERROR_EVENT Enables or disables specific error reporting: 0 = Disable 1 = Enable

H324_LINE_STAT_CMD_PERIODIC Enables or disables periodic error reporting: 0 = Disable 1 = Enable

H324_LINE_STAT_CMD_RESET_STAT Is not used.

param2

The param2 value depends upon the value selected for command:

If command is... The param2 value...

H324_LINE_STAT_CMD_ERROR_EVENT Is a bit mask used to select which error triggers an error report event. Bit mask values are: 1 = Video CRC error 2 = Audio CRC error 4 = Golay Coding error in PDU header

H324_LINE_STAT_CMD_PERIODIC Defines the time in seconds between periodic reports.

H324_LINE_STAT_CMD_RESET_STAT Is not used.



Return values


SUCCESS





Events

Event Description

MSPEVN_DEMUX_CRC_ERR_REPORT Demux has detected a line error, and is sending event data in a structure of the type msp_ENDPOINT_DEMUX_CRC_ERROR_REPORTS:

typedef struct tag_msp_ENDPOINT_DEMUX_CRC_ERROR_REPORTS { DWORD FilterId; WORD EvnBase; WORD EvnId; DWORD error_check_type; // 1 = video CRC check // 2 = audio CRC check // 4 = header Golay coding check DWORD total_num_errors; } msp_ENDPOINT_DEMUX_CRC_ERROR_REPORTS;

MSPEVN_DEMUX_PERIODIC_STATS Demux has sent its periodic error statistics. The buffer contains a structure of type msp_ENDPOINT_DEMUX_PERIODIC_STATS:

typedef struct tag_msp_ENDPOINT_DEMUX_PERIODIC_STATS { DWORD FilterId; WORD EvnBase; WORD EvnId; DWORD num_videoCRCerrors; DWORD num_videoCRCsuccesses; DWORD num_audioCRCerrors; DWORD num_audioCRCsuccesses; DWORD num_headerGolayerrors; DWORD num_headerGolaysuccesses; DWORD reserved1; // possibly use for control CRC reports later on DWORD reserved2; } msp_ENDPOINT_DEMUX_PERIODIC_STATS;



Example printf("\n\tEnable/Disable Periodic Statistics (0=Disable, 1=Enable) > "); fflush(stdin); scanf("%hd", &value1); printf("\n\tSet Periodic Statistics Interval (1-10 seconds X 10) > "); fflush(stdin); scanf("%hd", &value2); h324LineErrorReporting( GwConfig[0].MuxEp.hd, H324_LINE_STAT_CMD_PERIODIC, value1, value2); ... // received an asynchronous event: CTA_EVENT *pevent switch (pevent->value) { case (MSPEVN_DEMUX_PERIODIC_STATS): if((GwConfig[nGw].MuxEp.hd == pevent->objHd) && (pevent->buffer != NULL) && (pevent->size > 0)) ShowDemuxPeriodicStats(nGw, (msp_ENDPOINT_DEMUX_PERIODIC_STATS *)pevent->buffer); break; case (MSPEVN_DEMUX_CRC_ERR_REPORT): if(GwConfig[nGw].MuxEp.hd == pevent->objHd) { msp_ENDPOINT_DEMUX_CRC_ERROR_REPORTS *err = (msp_ENDPOINT_DEMUX_CRC_ERROR_REPORTS*)pevent->buffer; switch( NMS2H_DWORD(err->error_check_type) ) { case 1: // Video CRC Error printf("VIDEO CRC ERROR Received at Demux, Error Count = %d\n", NMS2H_DWORD(err->total_num_errors) ); break; case 2: // Audio CRC Error printf("AUDIO CRC ERROR Received at Demux, Error Count = %d\n", NMS2H_DWORD(err->total_num_errors) ); break; case 4: // Golay printf("HEADER GOLAY CODING ERROR Received at Demux, Error Count = %d\n", NMS2H_DWORD(err->total_num_errors) ); break; } } break;



h324OLCResponse

Lets the H.324M Middleware know whether to accept or reject an open logical channel (OLC) request offered by the remote terminal.

Prototype

DWORD h324OLCResponse ( MSPHD msphd, DWORD response, DWORD lcn)



response Set to H324_ACCEPT or H324_REJECT.

lcn Logical channel number of the proposed channel.

Return values


SUCCESS





Events

None.

Details

h324OLCResponse is called in response to an H324EVN_REMOTE_OLC event.

Note: Accepting an open logical channel implies that the application is ready to receive and process the media defined in the open logical channel. If audio transcoding is required, the audio channel must be set up prior to sending the h324OLCResponse Accept response, or serious errors could result.

Care must be taken when accepting video open logical channel. The application must only accept a remote OLC whose forward and reverse channel parameters match supported video format by the H.324M Interface, and by any other device involved in the complete system. Otherwise, the video OLC must be rejected.

For more information, refer to Setting up calls and media channels on page 21.

Example printf("Accept Remote Video OLC with codec %d. rx channel %d \n", l_pLCD->rxChoice, l_pLCD->rxChannel); ret = h324OLCResponse( pCfg->MuxEp.hd, H324_ACCEPT, l_pLCD->rxChannel ); if ( ret != SUCCESS) { printf("h324OLCResponse. Return code is %x\n", ret); return ret; }



h324RoundTripDelay

Sends a round trip delay to the remote terminal.

Prototype

DWORD h324RoundTripDelay ( MSPHD msphd)



Return values


SUCCESS





Events

Event Description

H324EVN_ROUND_TRIP_DELAY Remote terminal responded to the round trip delay message.

H324EVN_ROUND_TRIP_TIMEOUT Remote terminal did not respond.

Example ret = h324RoundTripDelay( GwConfig[0].MuxEp.hd ); if ( ret != SUCCESS) { printf("h324RoundTripDelay. Return code is %x\n", ret); return ret; }



h324SetTermCaps

Sets the local terminal capabilities for the terminal and initiates the transfer of the terminal capabilities set if h324SetupCall has already been called. These values are used in the terminal capabilities exchange and in the open logical channel messages.

Prototype

DWORD h324SetTermCaps ( MSPHD msphd, H324_TERM_CAPS *termCaps)



termCaps Pointer to the MUX and media capabilities of the terminal.

Return values


SUCCESS





Events

None.

Details

h324SetTermCaps allows you to modify capability parameters defined in h324Start. You cannot add or remove capabilities.

If termCaps = NULL, the default terminal capabilities are used.



Example ret = h324GetTermCaps( pCfg->MuxEp.hd, H324_LOCAL_TERMINAL, &pCfg->localTermCaps); if ( ret != SUCCESS) { printf("h324GetTermCaps. Return code is %x\n", ret); return ret; } printf("Call to Local h324GetTermCaps returned %d capabilities\n", pCfg->localTermCaps.wCapCount ); for(i=0;i<pCfg->localTermCaps.wCapCount;i++) { switch(pCfg->localTermCaps.capTable[i].choice) { case H324_H263_VIDEO: printf("Local Capability [%d] = %d (H263)\n", i, pCfg->localTermCaps.capTable[i].choice ); // Modify video max bitrate pCfg->localTermCaps.capTable[i].u.h263.mode.bit_rate = gwParm.h263_maxBitRate; pCfg->localTermCaps.capTable[i].u.h263.capability.max_bit_rate = gwParm.h263_maxBitRate; break; case H324_MPEG4_VIDEO: printf("Local Capability [%d] = %d (MPEG4)\n", i, pCfg->localTermCaps.capTable[i].choice ); // Modify video max bitrate pCfg->localTermCaps.capTable[i].u.mpeg4.mode.bit_rate = 43000; pCfg->localTermCaps.capTable[i].u.mpeg4.capability.max_bit_rate = 43000; break; case H324_G723_AUDIO: printf("Local Capability [%d] = %d (G723)\n", i, pCfg->localTermCaps.capTable[i].choice ); break; case H324_AMR_AUDIO: printf("Local Capability [%d] = %d (AMR)\n", i, pCfg->localTermCaps.capTable[i].choice ); break; } } ret = h324SetTermCaps( pCfg->MuxEp.hd, &pCfg->localTermCaps); { printf("h324GetTermCaps. Return code is %x\n", ret); return ret; }

For more information, refer to H.324M Middleware structures on page 88.



h324SetTrace

Defines the level of tracing for the H.324M Middleware. h324SetTrace can be called any time before or after h324Initialize.

Prototype

DWORD h324SetTrace ( unsigned int LogToConsoleMask, unsigned int LogToFileMask)


LogToConsoleMask Tracing mask for the console.

LogToFileMask Tracing mask for the log file.



The following bits can be turned on or off for both LogToConsoleMask and LogToFileMask:

Bit Value Description

T_H245 0x00001 H.245 negotiations.

T_H245INFO 0x00002 Print the contents of some H.245 messages in binary form.

T_H245ERR 0x00004 H.245 stack errors.

T_H245ECHO 0x00008 Prints information about the H.324M Middleware functions called by the application.

T_EVENT 0x00010 Prints events processed by h324SubmitEvent.

T_APPEVENT 0x00020 Prints events generated by the H.324M Middleware.

T_APIECHO 0x00040 Prints a message every time certain H.324M Middleware functions are called.

T_APIERR 0x00080 Prints more information in case of H.324M Middleware failures.

T_APIINFO 0x00100 Information about events consumed by the H.324M Middleware.

T_MUTEX 0x00200 Prints the message every time the internal H.324M mutex is locked or unlocked.

T_MUXIFINFO 0x00400 More information related to the communication with the MUX or DEMUX.

T_MUXIFECHO 0x00800 MUX or DEMUX interface functions.

T_MUXIFERR 0x01000 Errors while communicating with the MUX or DEMUX.

T_H245MSGSUM 0x02000 Prints NSRP related information.

T_H245MSGDET 0x04000 Prints detailed contents of H.245 messages received from the DEMUX in the binary form.

T_H245CALLB 0x08000 H.245 stack callback functions.

T_OLC 0x10000 Audio or video OLC state machine.

T_STACKINFO 0x20000 Reserved for future use.

T_STACKWARN 0x40000 Reserved for future use.

T_STACKERROR 0x80000 Reserved for future use.

T_ALL 0xFFFFF Full tracing.

T_ALLERR T_H245ERR + T_APIERR + T_MUXIFERR + T_STACKERROR + T_STACKWARN

Errors only.

T_NONE 0x00000 No tracing.



Return values


SUCCESS

Example

To not print messages on the screen and to print errors only to the log file: H324SetTrace( 0, T_ALLERR );



h324SetupCall

Informs the H.324M Middleware that it can begin terminal capability exchange and master slave determination when it is ready. This usually occurs when PMSYNC stops, indicating that the local and remote multiplexers are synchronized. For more information, refer to Setting up calls and media channels on page 21.

Prototype

DWORD h324SetupCall ( MSPHD msphd)



Return values


SUCCESS





Events

Event Description

H324EVN_CALL_SETUP_DONE Terminal capabilities exchange and master or slave determination is complete, and indicates success or failure.

Example case H324EVN_START_DONE: printf("Calling h324SetupCall\n"); ret = h324SetupCall(pCfg->MuxEp.hd); if(ret != SUCCESS) { printf("Error:h324SetupCall return 0x%08x\n",ret); return ret; }



h324SetupMedia

Tells the H.324M Middleware that open logical channel (OLC) and MUX table exchange can begin.

Prototype

DWORD h324SetupMedia ( MSPHD msphd)



Return values


SUCCESS





Events

Event Description

Event Description

H324EVN_MEDIA_SETUP_DONE OLC and MUX table exchange is complete and channels are established.

Details

Call setup must be complete before open logical channel and MUX table exchange can begin. Open logical channel messages will not be sent until h324DefineMediaChannel is called. For more information, refer to Setting up calls and media channels on page 21.

Example case H324EVN_CALL_SETUP_DONE: printf("Calling h324SetupMedia\n"); ret = h324SetupMedia(pCfg->MuxEp.hd); if(ret != SUCCESS) { printf("Error:h324SetupMedia returned 0x%08x\n",ret); return ret; }



h324Start

Creates an H.245 stack for the specified MUX and sets the initial values that are needed to begin an exchange with the client (such as resetting PMSYNC, and video sequence number.)

Prototype

DWORD h324Start ( CTAHD ctahd, MSPHD msphd, H324_START_PARAMS *params)


ctahd CTA handle for the application event queue.


params Pointer to the structure used to hold initial parameters for the H324 session:

typedef struct tag_H324_START_PARAMS { DWORD size; int terminalType; int iCapCount; int iCap[16]; } H324_START_PARAMS;

Return values


SUCCESS

H324ERR_INITIALIZE_STACK_FAILED Unable to initialize the H.245 stack.




Events

Event Description

H324EVN_START_DONE H.324M Middleware has been initialized for the specified MUX and provides a status code for success or failure.



Details

If no parameters are provided, a set of defaults are used. The parameters contain an array of the following capability types (iCap):

Value Description

0 H324_MPEG4_VIDEO

1 H324_H263_VIDEO

2 H324_H261_VIDEO

3 H324_G711_AUDIO

4 H324_G723_AUDIO

5 H324_AMR_AUDIO

Use the array to construct a terminal capabilities set, which you can then modify.

See also

h324Stop

Example example to declare a single Audio codec capability and single Video codec capability switch( gwParm.audioFormat ) { case N_AMR: params.iCap[0] = H324_AMR_AUDIO; break; case N_G723: params.iCap[0] = H324_G723_AUDIO; break; default: printf("Invalid audio format!\n"); return FAILURE; } switch( gwParm.videoFormat ) { case MPEG4: params.iCap[1] = H324_MPEG4_VIDEO; break; case H263: params.iCap[1] = H324_H263_VIDEO; break; default: printf("Invalid video format!\n"); return FAILURE; } ret = h324Start(pCtx->ctahd, pCfg->MuxEp.hd, &params); if(ret != SUCCESS) { printf("Error: h324Start returned 0x%08x\n",ret); return ret; }



h324Stop

Stops the H.324M Middleware for the specified MUX. Call this function at the end of an H.324M call.

Prototype

DWORD h324Stop ( MSPHD msphd)



Return values


SUCCESS





Events

Event Description

H324EVN_STOP_DONE H.324M Middleware has been stopped and provides a status code for success or failure. The application calls h324Delete when this event is received.

Example ret = h324Stop(GwConfig[i].MuxEp.hd); if (ret != SUCCESS) { printf("h324Stop returned 0x%x.\n", ret); return ret; } else { ret = WaitForSpecificEvent ( i, GwConfig[i].hCtaQueueHd, H324EVN_STOP_DONE, &event); if (ret != 0) { printf("H324EVN_STOP_DONE event failure, ret= %x, waitEvent.value=%x\n", ret, event.value); return ret; } }



h324SubmitEvent

Submits H.324M events from the event queue to the H.324M Middleware.

Prototype

DWORD h324SubmitEvent ( CTA_EVENT *event, BOOL *consumed)


event Pointer to an event received from ctaWaitEvent.

consumed Pointer to a returned value indicating if the H.324M Middleware has consumed the event.

Return values


SUCCESS

H324ERR_COMMAND_RESPONSE_ERROR A command done event received from an unexpected command.

H324ERR_INCOMING_MSG_ERROR Error processing an incoming H.245 message.



H324ERR_PMSYNC_ERROR Error after multiplexer synchronizes with remote multiplexer.

Events

None.

Details

h324SubmitEvent can either consume or not consume each event submitted to it. If the event is consumed, the application continues to wait for additional Natural Access events. If the event is not consumed, then it is an event for the application, and the application processes it normally.

The application does not release MSPP buffers associated with events that are consumed by h324SubmitEvent. These buffers are released by the H.324M Middleware.

See also

h324FormatEvent



Example CTA_EVENT event; BOOL consumed; while(1) { ctaWaitEvent(ctaqueuehd, &event, CTA_WAIT_FOREVER); ret = h324SubmitEvent(&event, &consumed); if(ret != SUCCESS) { /* Error processing */ } else if(consumed) continue; /* Normal application event processing goes here */ }



h324UserIndication

Sends a user indication (UII H.245 message) to the terminal.

Prototype

DWORD h324UserIndication ( MSPHD msphd, H324_USER_INPUT_INDICATION *msg)



msg Pointer to the structure that defines the user input indication message to be sent:

typedef struct tag_H324_USER_INPUT_INDICATION{ char data[H324_MAX_USER_INDICATION_SIZE]; DWORD length; char szObjectId[H324_MAX_UII_OBJECT_ID_SIZE]; DWORD msgType; } H324_USER_INPUT_INDICATION;

Return values


SUCCESS





Events

None.

Details

The user input indication message type can be defined as alphanumeric, nonstandard, or signal by setting msgType to H324_USER_INPUT_ALPHANUMERIC, H324_USER_INPUT_NONSTANDARD, or H324_USER_INPUT_SIGNAL. For the nonstandard user input indication, copy a zero terminated string into szObjectID to set the objectidentifier. This string is a dot separated number sequence, such as: 1.2.123.2345.5.73

An alphanumeric user input indication does not use the szObject ID field.

The size for H324_MAX_USER_INDICATION_SIZE = 512. The size for H324_MAX_UII_OBJECT_ID_SIZE = 128.



Example // sends “1234” alphanumeric string to the remote terminal l_UII.length = 4; l_UII.msgType = H324_USER_INPUT_ALPHANUMERIC; l_UII.szObjectId[0] = 0; strcpy( l_UII.data, "1234"); printf("UII length: %d\n", l_UII.length ); ret = h324UserIndication( GwConfig[Port].MuxEp.hd, &l_UII ); if( ret != SUCCESS ) printf("Failed to send the alphanumeric UII message...\n");



h324VendorIDIndication

Sends a vendor ID indication to the remote terminal.

Prototype

DWORD h324VendorIDIndication ( MSPHD msphd, H324_VENDORID_INDICATION *pVendorInd)



pVendorInd Pointer to the structure describing the VendorID indication to transmit.

Refer to Details for more information.

Return values


SUCCESS





Events

None.

Details

In the H324_VENDORID_INDICATION structure, the vendorID field is mandatory but the productNumber and versionNumber fields are optional, making this a variable-length structure. typedef struct tag_H324_VENDORID_INDICATION { unsigned short vendorIDLen; // Byte count for 1st field (vendorID) in bytes[]. unsigned short productNumberLen; // Byte count for 2nd field (productNumber) in bytes[]. unsigned short versionNumberLen; // Byte count for 3rd field (productVersion) in bytes[]. unsigned char isNonStandard; // NZ: nonstandard; 0: ObjectID unsigned char bytes[1]; // "vendorID" field resides at bytes[0] through bytes[vendorIDLen-1]. // OPTIONAL "productNumber" resides at bytes[vendorIDLen] // through bytes[vendorIDLen+productNumberLen-1]. // OPTIONAL "versionNumber" resides at bytes[vendorIDLen+productNumberLen] // through bytes[vendorIDLen+productNumberLen+versionNumberLen-1]. } H324_VENDORID_INDICATION;



The following table describes the fields in the H324_VENDORID_INDICATION structure:

Field Description

vendorId Per H.245, the vendorID field can be of two types:

• If the isNonStandard flag is true (NZ), vendorID is of type h221NonStandard.

• If the isNonStandard flag is false/zero, vendorID contains an ObjectID.

productNumber Field is present only if productNumberLen is not zero.

versionNumber Field is present only if versionNumberLen is not zero.

The locations of the three fields transmitted are as follows: vendorID: at bytes[0] for vendorIDLen bytes. productNumber: at bytes[vendorIDLen] for productNumberLen bytes. versionNumber: at bytes[vendorIDLen+productNumberLen] for versionNumberLen bytes.

Inbound H324EVN_VENDOR_INDICATION events use this structure to pass vendor ID indications to the application.

Example #include <h324def.h> unsigned char vendor_id[] = { 1, 28, 111, 97, 111, 84, 43, 86, 49 }; char prod_num[] = "N5000"; char vers_num[] = "1.23.5"; enum vendorIdType { t_ObjectId, t_h221NonStandard }; int sendVendorIDIndication(unsigned char * vendor_p, unsigned vendor_len, unsigned char * prodNum_p, unsigned prodNum_len, unsigned char * verNum_p, unsigned verNum_len, vendorIdType type, MSPHD msphd) { unsigned result, payloadSz = vendor_len + prodNum_len + verNum_len; H324_VENDORID_INDICATION * pVIBuf; if (!(pVIBuf = (H324_VENDORID_INDICATION *)malloc( sizeof(H324_VENDORID_INDICATION)+payloadSz))) return -1; memset(pVIBuf, 0, sizeof(H324_VENDORID_INDICATION) + payloadSz); // VendorID is either an ObjectID or H.221 NonStandard identifer. pVIBuf->isNonStandard = (type == t_h221NonStandard); // VendorID field lengths are required. pVIBuf->vendorIDLen = vendor_len; pVIBuf->productNumberLen = prodNum_len; // MBZ unless productNumber populated pVIBuf->versionNumberLen = verNum_len; // MBZ unless versionNumber populated // Copy required vendor ID into VendorID indication buffer. memcpy(&pVIBuf->bytes[0], vendor_p, vendor_len); // Copy optional productNumber and versionNumber fields, if present. if (prodNum_len) memcpy(&pVIBuf->bytes[vendor_len], prodNum_p, prodNum_len); if (verNum_len) memcpy(&pVIBuf->bytes[vendor_len + prodNum_len], verNum_p, verNum_len); // Send the VendorID indication. result = h324VendorIDIndication(msphd, pVIBuf); free(pVIBuf); if (result != SUCCESS) return -2; return 0; // VendorID successfully sent. }



h324VideoFastUpdate

Sends a video fast update message to the remote terminal.

Prototype

DWORD h324VideoFastUpdate ( MSPHD msphd)



Return values


SUCCESS





Events

None.

Example ret = h324VideoFastUpdate( GwConfig[nGw].MuxEp.hd ); if(ret != SUCCESS) { printf("Error:h324SetupMedia returned 0x%08x\n",ret); return ret; }



h324VideoTemporalSpatialTradeoff

Sends a VideoTemporalSpatialTradeoff message to the remote terminal.

Prototype

DWORD h324VideoTemporalSpatialTradeoff ( MSPHD msphd, unsigned short tradeoff)



tradeoff Temporal-spatial tradeoff value between 0..31 (unsigned integer).

Return values


SUCCESS





Events

None.

Details

A tradeoff value of zero indicates a high spatial resolution. A tradeoff value of 31 indicates a high frame rate. msphd identifies the MUX and the associated outbound video channel’s logical channel number.

Per H.245, values from 0 to 31 indicate monotonically a higher frame rate, and actual values do not correspond to precise values of spatial resolution or frame rate.

Example ret = h324VideoTemporalSpatialTradeoff(GwConfig[0].MuxEp.hd, tradeoff); if (ret == SUCCESS) printf("The videoTemporalSpatialTradeoff Indication message was sent successfully.\n"); else printf("Failed to send the videoTemporalSpatialTradeoff Indication message...\n");


66 H.324M Middleware call flow Call states

This topic explains how the H.324M Middleware functions and events are used to establish a call with an H.324M terminal. This topic defines the stages that the H.324M Middleware transitions through, and the calls that can be sent during each stage. It also defines the possible sequences of events when a call setup is working correctly, and when it fails.

During a call, each session of the H.324M Middleware passes through a sequence of states. The state transitions are driven by user commands, H.245 messages from the remote terminal, and internal actions of the H.324M Middleware. The following illustration shows these state transitions, followed by a detailed description of each of the following call states:

• Begin

• Created

• BeginCallSetup

• CallSetup

• BeginMediaSetup

• MediaSetup

• EndSession

• End

H.324M Middleware call flow H.324M Interface Manual


Begin

Created

BeginCallSetup

CallSetup

BeginMediaSetup

MediaSetup

EndSession

End

h324Start

H324EVN_START_DONE

h324SetupCall

H324EVN_CALL_SETUP_DONE

h324SetupMedia

H324EVN_MEDIA_SETUP_DONE

h324EndSession orH245 Msg EndSession

h324End

h324Delete

H324EVN_STOP_DONE

State transitions of the H.324M Middleware

StatesFunctions orcommands Events

H.324M Interface Manual H.324M Middleware call flow


Begin state

The H.245 stack is instantiated and data structures are created and initialized.

Enters state Upon receiving h324Start.

Exits state After the H.245 stack is instantiated and data structures are created and initialized. The state transition is signaled by the H324EVN_START_DONE event.

Related functions

None.

Normal events

H324EVN_START_DONE

Error events H324EVN_H245_INTERNAL_ERROR

Created state

Provides a holding point until the user is ready to begin call setup. During the Created state, MasterSlaveDetermination messages and TerminalCapabilitySet messages can be received from the remote terminal, but will not be sent.

Enters state Upon issuing the H324EVN_START_DONE event.

Exits state Upon receiving h324SetupCall, it transitions to the BeginCallSetup state.

or

Upon receipt of h324EndSession or receipt of the H.245 message EndSession, it transitions to the EndSession state. Upon receipt of h324Stop, it transitions to the End state.

Related functions

h324EndSession h324GetTermCaps h324SetTermCaps (but terminal capabilities are not sent until h324SetupCall) h324SetupCall h324Stop

Normal events

H324EVN_END_SESSION H324EVN_REMOTE_CAPABILITIES

Error events H324EVN_CALL_SETUP_FAILED H324EVN_H245_INTERNAL_ERROR



BeginCallSetup state

The following steps occur during this state:

• Master slave determination is completed

• Terminal capability set is sent and acknowledged

• Terminal capability set is received and acknowledged

Enters state Upon receiving h324SetupCall.

Exits state After master slave determination is completed, terminal capability set has been sent and acknowledged, and terminal capability set has been received and acknowledged, it transitions to the CallSetup state. The state transition is signaled by the H324EVN_CALL_SETUP_DONE event.

or

Upon receipt of h324EndSession or receipt of the H.245 EndSession message, it transitions to the EndSession state. Upon receipt of h324Stop, it transitions to the End state.

Related functions

h324EndSession h324GetTermCaps h324SetTermCaps h324Stop

Normal events

H324EVN_CALL_SETUP_DONE H324EVN_END_SESSION H324EVN_REMOTE_CAPABILITIES

Error events H324EVN_CALL_SETUP_FAILED H324EVN_H245_INTERNAL_ERROR

CallSetup state

Provides a holding point until the user is ready to begin media setup. While in the CallSetup state, MUX tables and OpenLogicalChannels can be received from the remote terminal, but none will be sent.

Enters state Upon issuing the H324EVN_CALL_SETUP_DONE event.

Exits state Upon receiving h324SetupMedia, it transitions to the BeginMediaSetup state.

or


Related functions

h324DefineMediaChannel h324EndSession h324OLCResponse h324SetupMedia h324Stop

Normal events

H324EVN_END_SESSION H324EVN_REMOTE_OLC

Error events H324EVN_H245_INTERNAL_ERROR H324EVN_MEDIA_SETUP_FAILED



BeginMediaSetup state

The following steps must be completed during this state:

• An OLC (open logical channel) for the incoming audio channel must be received and acknowledged.

• An OLC for the outgoing audio channel must be sent and acknowledged.

• An OLC for one bi-directional video channel must be sent, acknowledged, and confirmed (initiated by either the local or remote terminal). If a second bi-directional channel is opened, it must be closed.

OR

The H.324M Middleware must determine that it is not capable of setting up an acceptable bi-directional video channel.

• MUX table entries must be sent and acknowledged for all outgoing channels.

• MUX table entries must be received and acknowledged for all incoming channels.

Enters state Upon receiving h324SetupMedia.

Exits state When the steps stated above are completed, it transitions to the MediaSetup state. The state transition is signaled by the H324EVN_MEDIA_SETUP_DONE event.

or


Related functions

h324DefineMediaChannel h324EndSession h324OLCResponse h324Stop

Normal events

H324EVN_END_SESSION H324EVN_MEDIA_SETUP_DONE H324EVN_REMOTE_OLC H324EVN_VIDEO_FAST_UPDATE

Error events H324EVN_H245_INTERNAL_ERROR H324EVN_MEDIA_SETUP_FAILED H324EVN_VIDEO_CHANNEL_SETUP_FAILED



MediaSetup State

Media channels are open and the call is in progress.

Enters state Upon issuing the H324EVN_MEDIA_SETUP_DONE event.

Exits state Upon receipt of h324EndSession or receipt of the H.245 EndSession message, it transitions to the EndSession state. Upon receipt of h324Stop, it transitions to the End state.

Related functions

h324EndSession h324RoundTripDelay h324UserIndication h324VideoFastUpdate h324Stop

Normal events

H324EVN_END_SESSION H324EVN_ROUND_TRIP_DELAY H324EVN_USER_INDICATION H324EVN_VIDEO_FAST_UPDATE

Error events H324EVN_H245_INTERNAL_ERROR H324EVN_ROUND_TRIP_TIMEOUT

EndSession state

Sends out H.245 EndSession message, or processes incoming H.245 EndSession message, then waits to be shut down.

Enters state Upon receipt of h324EndSession or receipt of the H.245 EndSession message.

Exits state Upon receipt of h324Stop, it transitions to the End state.

Related functions h324Stop

Normal events None.


End state

Shuts down the H.245 stack.

Enters state Upon receipt of h324Stop.

Exits state When the H.245 stack has been shut down, the state is destroyed. This is signaled by the H324EVN_STOP_DONE event.

Related functions

None.

Normal events

H324EVN_STOP_DONE




Call flow components

The following call flow illustrations show the sequence of events for separate H.245 signaling entities. Flows are shown between the customer application, the H.324M Middleware, and the remote H.324 terminal. These call flows are samples of the events that can happen, but do not cover all possible cases.

Master slave determination

The following signaling entities operate independently, and therefore calls from each of these entities can be interspersed with each other:

• Master or slave determination

• Inbound terminal capabilities

• Outbound terminal capabilities

The call flows initiated by the local terminal occur during the BeginCallSetup state. Call flows initiated by the remote terminal occur during the Created state or the BeginCallSetup state.

The following illustration shows examples of successful master slave determinations:

Application Remote terminal

MasterSlaveDeterminationh324CallSetup

MasterSlaveDeterminationAck

OR

MasterSlaveDetermination

MasterSlaveDeterminationAckh324CallSetup

H324EVN_START_DONE

H324EVN_START_DONE

H.324MMiddleware

The following illustration shows an example of a failed master slave determination:


MasterSlaveDeterminationh324CallSetup

MasterSlaveDeterminationReject

H324EVN_START_DONE

H324EVN_CALL_SETUP_FAILED


MasterSlaveDeterminationReject

H.324MMiddleware

... Repeated retries ...



Terminal capabilities set

The following illustration shows examples of successful outbound terminal capability exchanges:


TerminalCapabilitiesSeth324CallSetup

TerminalCapabilitiesAck

H324EVN_START_DONE

h324SetTermCaps

TerminalCapabilitiesSet

h324CallSetup


H324EVN_START_DONE

h324SetTermCaps

OR

H.324MMiddleware

The following illustration shows examples of successful inbound terminal capability exchanges:



h324CallSetupTerminalCapabilitiesSet

h324CallSetup

OR

TerminalCapabilitiesSet


H.324MMiddleware



The following illustration shows an example of a failed outbound terminal capability exchange:


TerminalCapabilitiesSeth324CallSetup

TerminalCapabilitiesReject

h324SetTermCaps

H324EVN_CALL_SETUP_FAILED

H.324M Middleware



Multiplex table entry

The following signaling entities operate independently, and therefore calls from each of these entities can be interspersed with each other:

• Inbound multiplex table entry

• Outbound multiplex table entry

• Inbound audio open logical channel

• Outbound audio open logical channel

• Video open logical channel

The call flows initiated by the local terminal occur during the BeginMediaSetup state. Call flows initiated by the remote terminal occur during the CallSetup state or the BeginMediaSetup state.

The following illustration shows an example of a successful outbound multiplex table entry exchange:


h324SetupMediaMultiplexEntrySend

MultiplexEntrySendAck

H.324MMiddleware

The following illustration shows examples of successful inbound multiplex table entry exchanges:


h324SetupMedia



OR

MultiplexEntrySend

MultiplexEntrySend

H.324MMiddleware

h324SetupMedia

The following illustration shows an example of a failed outbound multiplex table entry exchange:


h324SetupMediaMultiplexEntrySend

H324EVN_MEDIA_SETUP_FAILED

MultiplexEntrySendReject

H.324MMiddleware



Audio open logical channel

The following illustration shows an example of a successful outbound audio open logical channel:


h324SetupMedia

OpenLogicalChannel

OpenLogicalChannelAck


H.324MMiddleware

The following illustration shows an example of a successful inbound audio open logical channel:


OpenLogicalChannel


H324EVN_REMOTE_OLC

h324OLCResponse (accept)

H.324MMiddleware

The following illustration shows an example of a failed outbound audio open logical channel:


h324SetupMedia

H324EVN_MEDIA_SETUP_FAILED

OpenLogicalChannel


OpenLogicalChannelReject

H.324MMiddleware



Video open logical channel

The following illustration shows successful video open logical channel examples:

Application H.324MMiddleware Remote terminal

h324SetupMedia

OpenLogicalChannel




OpenLogicalChannel

H324EVN_BI_CHANNEL_DESC

OpenLogicalChannelConfirm

h324SetupMedia

OpenLogicalChannelH324EVN_REMOTE_OLC

h324OLCResponse (accept)OpenLogicalChannelAck

OpenLogicalChannelConfirmh324DefineMediaChannel


h324SetupMedia


h324OLCResponse (reject)OpenLogicalChannelReject



OpenLogicalChannel


OpenLogicalChannel


OpenLogicalChannelConfirm

OR

OR



The following illustration shows a failed video open logical channel example:

Application H.324MMiddleware Remote terminal

h324SetupMedia


h324OLCResponse (reject)OpenLogicalChannelReject


H324EVN_VIDEO_CHANNEL_SETUP_FAILED

OpenLogicalChannel


OpenLogicalChannel


Call flow examples

The following illustrations show examples of complete call flows between the application and the 3G terminal. Several signaling entities are working simultaneously and independently, therefore the call flows shown in these illustrations can happen in many other orders.



The following call flow illustration presents an example of the application initiating the call, the 3G terminal is master, and the application proposes video first:

3G terminal

MasterSlaveDeterminationh324SetupCall

h324SetTermCaps

h324Start

MasterSlaveAck


TerminalCapabilities


TerminalCapabilitiesH324EVN_REMOTE_CAPS


OLC Audio

h324GetTermCaps

OLC Ack

OLC Audio

h324SetupMedia


OLC Ack

OLC Videoh324DefineMediaChannel

OLC Video

H324EVN_REMOTE_OLC

H324EVN_MEDIA_SETUP_DONEh324OLCResponse (Accept)

H324EVN_REMOTE_OLC

h324OLCResponse (Reject) OLC Reject

OLC Reject

OLC VideoOLC Accept

Call

setu

p (c

apab

ility

exc

hang

ean

d m

aste

r/sl

ave

dete

rmin

atio

n)Au

dio

setu

pVi

deo

setu

pCa

ll in

pro

gres

sCa

ll te

ardo

wn

h324VideoFastUpdate Video Fast Update

h324UserIndication User Indication

h324RoundTripDelay RoundTripDelay

RoundTripDelay ResponseH324EVN_ROUND_TRIP_DELAY

VideoFastUpdateH324EVN_VIDEO_FAST_UPDATE

UserIndicationH324EVN_USER_INDICATION

EndSessionH324EVN_END_SESSION

h324Stop

Disconnect ISDN call

H324EVN_STOP_DONE

H324EVN_START_DONE

MU

X se

tupMux Table

Mux Table Ack

Mux Table Ack

Mux Table


OLC ConfirmH324EVN_BI_CHANNEL_DESC

h324Delete

MasterSlaveAck (3G terminal=master)

Application

Place and connect ISDN call

H.324MMiddleware



The following call flow illustration presents an example of the 3G terminal initiating the call, the 3G terminal is master, and the 3G terminal proposes video first:

3G terminal


h324SetTermCaps

MasterSlaveAck






OLC Audio

h324GetTermCaps

OLC Ack

OLC Audio

h324SetupMedia


OLC Ack


OLC Video

H324EVN_REMOTE_OLC

h324OLCResponse (Accept)

H324EVN_REMOTE_OLC


OLC Accept

Call

setu

p (c

apab

ility

exc

hang

ean

d m

aste

r/sl

ave

dete

rmin

atio

n)Au

dio

setu

pVi

deo

setu

pCa

ll in

pro

gres

sCa

ll te

ardo

wn








h324Stop

H324EVN_STOP_DONE

H324EVN_START_DONE


MU

X se

tupMux Table

Mux Table Ack

Mux Table Ack

Mux Table

OLC ConfirmH324EVN_BI_CHANNEL_DESC

h324Delete

MasterSlaveAck (3G terminal=master)

Application


H.324MMiddleware

h324Start



The following call flow illustration presents an example of the application initiating the call, the 3G terminal is slave, and the application proposes video first:

3G terminal


h324SetTermCaps

h324Start

MasterSlaveAck






OLC Audio

h324GetTermCaps

OLC Ack

OLC Audio

h324SetupMedia


OLC Ack


OLC Video

H324EVN_REMOTE_OLC

H324EVN_MEDIA_SETUP_DONE

h324OLCResponse (Accept)

H324EVN_REMOTE_OLC


OLC Reject

OLC Accept

OLC Video

Call

setu

p (c

apab

ility

exc

hang

ean

d m

aste

r/sl

ave

dete

rmin

atio

n)Au

dio

setu

pVi

deo

setu

pCa

ll in

pro

gres

sCa

ll te

ardo

wn







h324Stop


h324EndSession End Session

H324EVN_STOP_DONE

H324EVN_START_DONE

MU

X se

tupMux Table

Mux Table Ack

Mux Table Ack

Mux Table

OLC Confirm


h324Delete

MasterSlaveAck (3G terminal=slave)

Application


H.324MMiddleware


77 Errors, events, structures, and reason codes

Alphabetical error summary

All functions return a status code. If the return code is not SUCCESS (0), it is an error code indicating that the function failed and the reason for the failure.

H.324M Middleware error codes are defined in the h324def.h include file. The error codes are prefixed with H324ERR.

For errors beginning with CTAERR, refer to the Natural Access Developer's Reference Manual.

The following table lists the H.324M Middleware errors. All errors are 32 bits.

Error Hex Decimal Description

H324ERR_ALREADY_INITIALIZED 0x520001 5373953 h324Initialize has already been called.

H324ERR_COMMAND_RESPONSE_ERROR 0x520008 5373960 A command done event received from an unexpected command.

H324ERR_INCOMING_MSG_ERROR 0x520007 5373959 Error processing an incoming H.245 message.

H324ERR_INITIALIZE_STACK_FAILED 0x520006 5373958 Unable to initialize the H.245 stack.

H324ERR_INTERNAL_ERROR 0x520005 5373957 Internal error in H.324M Middleware.

H324ERR_LOG_FILE_OPEN_FAILED 0x52000b 5373963 Error opening the log file.

H324ERR_MUTEX_CREATE_FAILED 0x520002 5373954 Failed to create mutex semaphore.

H324ERR_MUTEX_LOCK_FAILED 0x520004 5373956 Internal error trying to lock mutex.

H324ERR_NOT_INITIALIZED 0x520003 5373955 H.324M Middleware is not initialized. Call h324Initialize first.

H324ERR_OUT_OF_MEMORY 0x52000a 5373962 Failed to allocate memory.

H324ERR_PMSYNC_ERROR 0x520009 5373961 Error after multiplexer synchronizes with remote multiplexer.

Errors, events, structures, and reason codes H.324M Interface Manual


Numerical error summary

The following table lists the H.324M Interface errors:

Hex Decimal Error

0x520001 5373953 H324ERR_ALREADY_INITIALIZED

0x520002 5373954 H324ERR_MUTEX_CREATE_FAILED

0x520003 5373955 H324ERR_NOT_INITIALIZED

0x520004 5373956 H324ERR_MUTEX_LOCK_FAILED

0x520005 5373957 H324ERR_INTERNAL_ERROR

0x520006 5373958 H324ERR_INITIALIZE_STACK_FAILED

0x520007 5373959 H324ERR_INCOMING_MSG_ERROR

0x520008 5373960 H324ERR_COMMAND_RESPONSE_ERROR

0x520009 5373961 H324ERR_PMSYNC_ERROR

0x52000a 5373962 H324ERR_OUT_OF_MEMORY

0x52000b 5373963 H324ERR_LOG_FILE_OPEN_FAILED

H.324M Interface Manual Errors, events, structures, and reason codes


Events

The events listed in this topic can be sent by the H.324M Middleware to the application.

For events that have an attached buffer, it is the responsibility of the application to free this buffer after the application is done using it. The event size field defines the size of the buffer in bytes.

For events with no attached buffer, but with reason codes, the reason codes are contained in the event size field.

Event Hex Decimal Description

H324EVN_BI_CHANNEL_DESC 0x52200E 5382158 A description of the final bi-directional channel established for bi-directional video or audio. This description is provided in the event buffer as a structure of type H324_LCD.

H324EVN_CALL_SETUP_DONE 0x522002 5382146 H.245 negotiations have completed the call setup phase. Terminal capabilities have been exchanged between both terminals, and master or slave determination is complete. No media has been set up.

H324EVN_CALL_SETUP_ FAILED

0x522010 5382160 Call setup failed due to a failure of either the master slave determination or the terminal capabilities exchange. One of the following reason codes is returned:

H324RSN_TERM_CAP_REJECT_UNSPECIFIED

H324RSN_TERM_CAP_REJECT_UNDEFINED_TABLE_ ENTRY_USED

H324RSN_TERM_CAP_REJECT_DESCRIPTOR_CAPACITY_ EXCEEDED

H324RSN_TERM_CAP_REJECT_TABLE_ENTRY_CAPACITY_ EXCEEDED

H324RSN_TERM_CAP_TIME_OUT

H324RSN_MASTER_SLAVE_ERROR

H324RSN_UNSPECIFIED

Shut down the call by calling h324Stop and h324Delete.

H324EVN_CHANNEL_CLOSED 0x522013 5382163 Local or remote terminal successfully closed a channel. The type of the channel closed can be found in the event size field. The event size field contains one of the following values:

H324RSN_AUDIO_IN H324RSN_AUDIO_OUT H324RSN_VIDEO

H324EVN_END_SESSION 0x522007 5382151 Remote terminal sent an H.245 EndSession command. This event initiates call teardown. The H.324M Middleware does not expect any further commands beyond h324Stop and h324Delete. No further incoming H.324 events except H324EVN_STOP_DONE is expected. Many terminals do not send H324EVN_END_SESSION prior to terminating the call.

H324EVN_END_SESSION_ DONE

0x522016 5382166 End session message was delivered to the remote terminal.




H324EVN_END_SESSION_ TIMER_EXPIRED

0x522015 5382165 An internal event to be consumed by h324SubmitEvent. If the event is not consumed, the application must ignore it. The event may not be consumed if the corresponding instance of the H.245 stack was destroyed before submitting the event to the H.324M Middleware.

H324EVN_H223_SKEW_ INDICATION

0x522017 5382167 An H.223 skew indication received from the terminal indicates that one channel, either audio or video, is delayed with respect to the other. Applying a corresponding delay to the other channel resynchronizes playback of the two channels. An H324_H223_SKEW_INDICATION structure in the event buffer specifies the skewType of either audioLate or videoLate and skewInMs. (Refer to h324_h223SkewIndication.) The logical channel numbers reported by H.245 are also included. The H.324M Interface does not provide a resynchronization mechanism.

H324EVN_H245_INTERNAL_ ERROR

0x52200F 5382159 H.245 stack has declared an internal error of an undefined type. Recommended resolution is to shut down the call.

H324EVN_MEDIA_SETUP_ DONE

0x522005 5382149 A complete set of open logical channels (OLCs) has been sent by the remote terminal, and acknowledged by the H.324M Middleware. The H.324M Middleware has sent a full set of OLCs that were acknowledged by the remote terminal. Also, each side has sent MUX tables, which were acknowledged by the other side. Media can now flow.

H324EVN_MEDIA_SETUP_ FAILED

0x522011 5382161 Media setup failed due to a failure of either the multiplex entry table, or one of the audio channels. One of the following reason codes is returned:

H324RSN_MUX_TABLE_REJECT_UNSPECIFIED

H324RSN_MUX_TABLE_REJECT_DESCRIPTOR_TOO_ COMPLEX

H324RSN_INBOUND_AUDIO_CHANNEL_FAILURE

H324RSN_OUTBOUND_AUDIO_CHANNEL_FAILURE

H324RSN_LCSE_ERROR_INDICATION

H324RSN_UNSPECIFIED

Shut down the call by calling h324Stop and h324Delete.

H324EVN_REMOTE_ CAPABILITIES

0x522003 5382147 A terminal capabilities set has been received from the remote terminal. The contents of this set are reflected in the event buffer as a structure of type H324_TERM_CAPS.

H324EVN_REMOTE_OLC 0x522004 5382148 Remote terminal has requested an open logical channel. A description of the requested channel is provided in the event buffer as a structure of type logical type description. Refer to H324_LCD.

H324EVN_ROUND_TRIP_ DELAY

0x522009 5382153 Results of round trip delay request.

H324EVN_ROUND_TRIP_ TIMEOUT

0x52200A 5382154 Timeout after a round trip delay message was sent.

H324EVN_START_DONE 0x522000 5382144 Received when the H.245 stack creation is complete. The event value indicates success or failure.




H324EVN_STOP_DONE 0x52200B 5382155 Received when the H.245 stack destruction is complete. The event value indicates success or failure. The application must call h324Delete when this event is received.

H324EVN_USER_INDICATION 0x522008 5382152 Remote terminal sent a user indication. The event buffer contains the message in the H324_USER_INPUT_INDICATION structure. Refer to the structure shown in h324UserIndication.

H324EVN_VENDORID_ INDICATION

0x522018 5382168 Vendor indication received from the terminal. The event buffer contains the message in a structure of the type H324_VENDORID_INDICATION, described in h324VendorIDIndication.

H324EVN_VIDEO_CHANNEL_ SETUP_FAILED

0x522012 5382162 After multiple retries, the H.324M Middleware could not establish a bi-directional video channel. The call can continue as an audio only call, or can be shut down by calling h324Stop and h324Delete.

H324EVN_VIDEO_FAST_ UPDATE

0x522006 5382150 Remote terminal has requested a video fast update.

H324EVN_VIDEO_OLC_TIMER_ EXPIRED

0x522014 5382164 An internal event to be consumed by h324SubmitEvent. If the event is not consumed, the application must ignore it. The event may not be consumed if the corresponding instance of the H.245 stack was destroyed before submitting the event to the H.324M Middleware.

H324EVN_VIDEOTEMPORAL SPATIALTRADEOFF_ INDICATION

0x522019 5382169 A VideoTemporalSpatialTradeoff Indication event was received from the terminal. The H324_VIDEOTEMPORALSPATIALTRADEOFF_ INDICATION structure in the event buffer, specifies the logical channel number of the remote outbound video channel and the updated temporal-spatial tradeoff value for that video channel. Tradeoff values range from 0 to 31, with a tradeoff value of 0 indicating a high spatial resolution and a tradeoff value of 31 indicating a high frame rate.



MSPP video structures

This topic presents the H.324M Interface structures for creating MSPP endpoints and channels.

Structures for creating MSPP endpoints

The following H.324M Interface structures are used to create MSPP endpoints:

• MSP_ENDPOINT_ADDR

• MSP_ENDPOINT_PARAMETER

• MUX_ENDPOINT_ADDR

• RTPRTCP_ENDPOINT_ADDR

• RTPRTCP_ENDPOINT_PARMS

• RTP_PAYLOAD_MAP

MSP_ENDPOINT_ADDR

Use the MSP_ENDPOINT_ADDR and MSP_ENDPOINT_PARAMETER structures to create MUX endpoints and audio and video RTP endpoints. typedef struct tag_MSP_ENDPOINT_ADDR { DWORD size; // ENDPOINT_ADDR DWORD nBoard; // board number DWORD eEpType; // MSP_ENDPOINT_DS0, MSP_ENDPOINT_RTPFDX, etc union { DS0_ENDPOINT_ADDR DS0; PKTMEDIA_ENDPOINT_ADDR Pktmedia; MONITOR_ENDPOINT_ADDR Monitor; RTPRTCP_ENDPOINT_ADDR RtpRtcp; UDP_ENDPOINT_ADDR Udp; T38UDP_ENDPOINT_ADDR T38Udp; MUX_ENDPOINT_ADDR Mux; // New endpoints to support IPv6 RTPRTCP_V6_ENDPOINT_ADDR RtpRtcpV6 UPD_V6_ENDPOINT_ADDR UdpV6 // Structure may be expanded to define new Endpoints } EP; } MSP_ENDPOINT_ADDR;



MSP_ENDPOINT_PARAMETER typedef struct tag_MSP_ENDPOINT_PARMS { DWORD size; // size of MSP_ENDPOINT_PARAMS) DWORD eParmType; // MSP_ENDPOINT_DS0, MSP_ENDPOINT_RTPFDX, etc union { DS0_ENDPOINT_PARMS DS0; PKTMEDIA_ENDPOINT_PARMS Pktmedia; MONITOR_ENPOINT_PARMS Monitor; RTPRTCP_ENDPOINT_PARMS RtpRtcp; UDP_ENDPOINT_PARMS Udp; T38UDP_ENDPOINT_PARMS T38Udp; TPKT_ENDPOINT_PARMS Tpkt; MUX_ENDPOINT_PARMS Mux; UNDEFINED_ENDPOINT_PARMS Undefined; // Structure may be expanded to define new Endpoints RTPRTCP_V6_ENDPOINT_PARMS RtpRtcpV6 UPD_V6_ENDPOINT_PARMS UdpV6 } EP; } MSP_ENDPOINT_PARAMETER;

MUX_ENDPOINT_ADDR

The MUX_ENDPOINT_ADDR structure sets the timeslot of a MUX endpoint: typedef struct tag_MUX_ENDPOINT_ADDR { // Address attributes DWORD nTimeslot; // Timeslot address } MUX_ENDPOINT_ADDR;

RTPRTCP_ENDPOINT_ADDR

The RTPRTCP_ENDPOINT_ADDR structure defines the RTP IP address and port numbers of the RTP endpoint source and destination: typedef struct tag_RTPRTCP_ENDPOINT_ADDR { // RTP parameters char DestIpAddress[20]; // destination IP address in dot notation WORD nDestPort; // destination port number char SrcIpAddress[20]; // source IP address in dot notation WORD nSrcPort; // source port number } RTPRTCP_ENDPOINT_ADDR;



RTPRTCP_ENDPOINT_PARMS

The RTPRTCP_ENDPOINT_PARMS structure sets RTP endpoint configuration parameters: typedef struct tag_RTPRTCP_ENDPOINT_PARMS { DWORD size; // QoS parameters BYTE TypeOfService; // Default = 0, type of service in IP header DWORD startRtcp; // Set this to non-zero to start RTCP // session. RTCP_SESSION_PARMS structure must be // filled in for the RTCP session /* RTCP parameters */ RTCP_SESSION_PARMS rtcpParms; DWORD RtpTsFreq; // Default=8000, timestamp frequency // For a Video Endpoint, RtpTsFreq is fixed to 90000 // and cannot be modified DWORD Session_bw; // Default=64000, session bandwidth DWORD dtmf_event_control; // Control DTMF RTP Event generation DWORD frameQuota; // RTP Assembly frame quota // For a Video Endpoint, frameQuota is fixed to 1 // and cannot be modified DWORD linkEvents; // Controls link events RTP_PAYLOAD_MAP PayloadMap; } RTPRTCP_ENDPOINT_PARMS;

RTP_PAYLOAD_MAP

The RTP_PAYLOAD_MAP structure assigns a payload ID to a vocoder: typedef struct tag_RTP_PAYLOAD_MAP { DWORD vocoder; DWORD payload_id; } RTP_PAYLOAD_MAP;

For video endpoints, use:

• 100 for MPEG-4 vocoder. 100 is the default payload ID.

• 34 for H.263 vocoder. 34 is the default payload ID.



Structures for creating MSPP channels

The following H.324M Interface structures are used to create MSPP channels:

• MSP_CHANNEL_ADDR

• MSP_CHANNEL_PARAMETER

• MSP_VIDEO_CHANNEL_PARMS

• MSP_AUDIO_CHANNEL_PARMS

MSP_CHANNEL_ADDR

Use the MSP_CHANNEL_ADDR and MSP_CHANNEL_PARAMETER structures to create audio and video MSPP channels. typedef struct tag_MSP_CHANNEL_ADDR { DWORD size; DWORD nBoard; // Channel location (board number) MSP_CHANNEL_TYPE channelType; DWORD FilterAttribs; // Used to enable DSP Filter functions } MSP_CHANNEL_ADDR;

MSP_CHANNEL_PARAMETER typedef struct tag_MSP_CHANNEL_PARMS { DWORD size; MSP_CHANNEL_TYPE channelType; union { MSP_VOICE_CHANNEL_PARMS VoiceParms; MSP_FAX_CHANNEL_PARMS FaxParms; MSP_RTP_SWITCHING_CHANNEL_PARMS RtpSwitchingParms; MSP_VIDEO_CHANNEL_PARMS VideoParms; MSP_AUDIO_CHANNEL_PARMS AudioParms; MSP_UNDEFINED_CHANNEL_PARMS Undefined; // Structure may be expanded to define new Channel Types } ChannelParms; } MSP_CHANNEL_PARAMETER;

MSP_VIDEO_CHANNEL_PARMS

The MSP_VIDEO_CHANNEL_PARMS structure defines the video jitter buffer parameters. These parameters cannot be changed. typedef struct tag_MSP_VIDEO_CHANNEL_PARMS { DWORD size; msp_FILTER_JITTER_PARMS JitterParms; // Video Jitter parameters cannot // be modified } MSP_VIDEO_CHANNEL_PARMS;

MSP_AUDIO_CHANNEL_PARMS

The MSP_AUDIO_CHANNEL_PARMS structure defines the MSPP channel used for AMR transcoding in the H.324M Interface: typedef struct tag_MSP_AUDIO_CHANNEL_PARMS { DWORD size; msp_FILTER_ENCODER_PARMS EncoderParms; msp_FILTER_DECODER_PARMS DecoderParms; } MSP_AUDIO_CHANNEL_PARMS;



H.324M Middleware structures

This topic presents the following H.324M Interface structures related to the H.324M Middleware:

• H324_H223_SKEW_INDICATION

• H324_LCD

• H324_START_PARAMS

• H324_TERM_CAPS

• H324_USER_INPUT_INDICATION

• H324_VENDORID_INDICATION

• H324_VIDEOTEMPORALSPATIALTRADEOFF_INDICATION

H324_H223_SKEW_INDICATION

typedef struct tag_H324_H223_SKEW_INDICATION { channelSkewType skewType; // audioLate | videoLate unsigned int skewInMs; // Channel delay in ms. [INT: 0..4095] unsigned int logicalChannelNumber1; // Channel delayed [INT: 1..65535] unsigned int logicalChannelNumber2; // Channel requiring delay [INT: 1..65535] } H324_H223_SKEW_INDICATION;

H324_LCD

typedef struct tag_H324_LCD{ // Receive Info BOOL bReceive; int rxChannel; DWORD rxChoice; MEDIA_UNION rxU; // Transmit Info BOOL bTransmit; int txChannel; DWORD txChoice; MEDIA_UNION txU; }H324_LCD;

H324_START_PARAMS

typedef struct tag_H324_START_PARAMS{ DWORD size; int terminalType; int iCapCount; int iCap[16]; } H324_START_PARAMS;



H324_TERM_CAPS

typedef struct tag_MULTIPLEX_CAPABILITY { BOOL dataWithAL1; BOOL audioWithAL2; BOOL videoWithAL2; BOOL videoWithAL3; WORD maximumAL1MPDUSize; WORD maximumAL2MSDUSize; WORD maximumAL3MSDUSize; #ifdef EXTENDED_CAPS BOOL videoWithAL1; BOOL audioWithAL1; BOOL audioWithAL3; BOOL dataWithAL2; BOOL dataWithAL3; BOOL alpduInterleaving; BOOL rsCodeCapability; #endif } MULTIPLEX_CAPABILITY; typedef union tag_MEDIA_UNION{ MMP4VIDEOOPTIONS mpeg4; MH263OPTIONS h263; MH261OPTIONS h261; MG711OPTIONS g711; MG7231OPTIONS g723; MGSMAMROPTIONS gsmamr; } MEDIA_UNION; typedef struct tag_MEDIA_CAPABILITY { BOOL bReceive; BOOL bTransmit; int index; DWORD choice; #define H324_MPEG4_VIDEO 0 #define H324_H263_VIDEO 1 #define H324_H261_VIDEO 2 #define H324_G711_AUDIO 3 #define H324_G723_AUDIO 4 #define H324_AMR_AUDIO 5 DWORD size; MEDIA_UNION u; } H324_MEDIA_CAPABILITY; typedef struct tag_H324_TERM_CAPS{ DWORD size; MULTIPLEX_CAPABILITY muxCap; DWORD wCapCount; // Number of caps H324_MEDIA_CAPABILITY capTable[16]; } H324_TERM_CAPS;

H324_USER_INPUT_INDICATION

typedef struct tag_H324_USER_INPUT_INDICATION{ char data[H324_MAX_USER_INDICATION_SIZE]; DWORD length; char szObjectId[H324_MAX_UII_OBJECT_ID_SIZE]; DWORD msgType; } H324_USER_INPUT_INDICATION;



H324_VENDORID_INDICATION

typedef struct tag_H324_VENDORID_INDICATION { unsigned short vendorIDLen; // Byte count for 1st field (vendorID) in bytes[] below. unsigned short productNumberLen; // Byte count for 2nd field (productNumber) in bytes[] below. unsigned short versionNumberLen; // Byte count for 3rd field (productVersion) in bytes[] below. unsigned char isNonStandard; // NZ: nonstandard; 0: ObjectID unsigned char bytes[sizeof(char)]; // "vendorID" field resides at bytes[0] through bytes[vendorIDLen-1]. // OPTIONAL "productNumber" resides at bytes[vendorIDLen] // through bytes[vendorIDLen+productNumberLen-1]. // OPTIONAL "versionNumber" resides at bytes[vendorIDLen+productNumberLen] // through bytes[vendorIDLen+productNumberLen+versionNumberLen-1]. } H324_VENDORID_INDICATION;

H324_VIDEOTEMPORALSPATIALTRADEOFF_INDICATION

typedef struct tag_H324_VIDEOTEMPORALSPATIALTRADEOFF_INDICATION { unsigned int logicalChannelNumber; // LCN affected by new tradeoff value unsigned int tradeoff; // New temporal-spatial tradeoff value } H324_VIDEOTEMPORALSPATIALTRADEOFF_INDICATION;



Reason codes

The following table lists the H.324M Interface reason codes:

Reason code Hex Decimal Description

H324RSN_AUDIO_IN 0x000020 0000032 Audio inbound channel identifier.

H324RSN_AUDIO_OUT 0x000021 0000033 Audio outbound channel identifier.

H324RSN_INBOUND_AUDIO_CHANNEL_FAILURE 0x00000B 0000011 Failure to establish audio on an inbound channel.

H324RSN_LCSE_ERROR_INDICATION 0x00000D 0000013 Indication of an OLC error sent by the remote terminal.

H324RSN_MASTER_SLAVE_ERROR 0x000007 0000007 Master/slave determination procedure failed.

H324RSN_MUX_TABLE_REJECT_DESCRIPTOR_ TOO_COMPLEX

0x000009 0000009 Multiplex table was rejected by the remote terminal. The MultiplexEntryDescriptor exceeded the capability of the receive terminal.

H324RSN_MUX_TABLE_REJECT_UNSPECIFIED 0x000008 0000008 Multiplex table was not specified.

H324RSN_MUX_TABLE_TIME_OUT 0x00000A 0000010 Timeout occurred during the multiplex tables exchange procedure.

H324RSN_OUTBOUND_AUDIO_CHANNEL_FAILURE 0x00000C 0000012 Failure to establish audio on an outbound channel.

H324RSN_TERM_CAP_ERROR_UNSPECIFIED 0x000006 0000006 Could not send the terminal capabilities set to the remote terminal.

H324RSN_TERM_CAP_REJECT_DESCRIPTOR_ CAPACITY_EXCEEDED

0x000002 0000002 The remote terminal could not store the information in the TerminalCapabilitySet.

H324RSN_TERM_CAP_REJECT_TABLE_ENTRY_ CAPACITY_EXCEEDED

0x000003 0000003 The remote terminal could not store more entries than indicated in highestEntryNumberProcessed or could not store any entries.

H324RSN_TERM_CAP_REJECT_UNDEFINED_TABLE_ ENTRY_USED

0x000001 0000001 A capability descriptor made reference to a capabilityTable entry that is not defined.

H324RSN_TERM_CAP_REJECT_UNSPECIFIED 0x000000 0000000 No cause for rejection was specified by the remote terminal.

H324RSN_TERM_CAP_REMOTE_REJECT 0x000005 0000005 Terminal capability set was rejected.

H324RSN_TERM_CAP_TIME_OUT 0x000004 0000004 Timeout occurred during terminal capabilities exchange procedure.



Reason code Hex Decimal Description

H324RSN_UNSPECIFIED 0x00000E 0000014 Unspecified channel identifier.

H324RSN_VIDEO 0x000022 0000034 Video channel identifier.


88 Glossary

# 2.5G: Advanced second generation wireless technology. 2.5G services can support

flexible data transmission rates typically up to 20 or 30 kbit/s.

2G: Second generation wireless technology.

3G: Next generation of wireless applications beyond personal communications services. It represents a move from circuit-switched communications (where a user device dials into a network) to broadband, high-speed, packet-based wireless networks. 3G networks transmit wireless data at 144 kbit/s at mobile user speeds, 384 kbit/s at pedestrian user speeds, and 2 Mbit/s in fixed locations.

A ADI service: A Natural Access service that provides all NMS Communications board

device-level functionality. Functions are provided for establishing and maintaining network connections, determining call status, playing and recording voice messages, and generating and detecting DTMF and other tones.

AL: Adaptation layer

AMR: Adaptive multi rate

AMR-NB: Adaptive multi rate - narrow band

ASR: Automatic speech recognition.

C CG boards: High performance, media processing NMS boards

channel: A simplex or full-duplex connection used to transcode between RTP transported H.263 and MPEG-4 video streams. Channels are mapped to transcoder resources by the TRC (Transcoder Resource Controller) as requested by the controlling application.

codec: A coder/decoder device that converts digital signals to analog, and analog signals to digital

context: In Natural Access, an entity that organizes services and accompanying resources around a logical processing unit. Usually represents an application thread performing a related set of functions, such as controlling a telephone call. Some contexts are not associated with a call; an application performing voice conversions does not require a telephone line.

context handle: In Natural Access, a programming reference to the allocated context.

Glossary H.324M Interface Manual


D DCI: Decoder configuration information.

DTMF: Dual tone multi-frequency tone.

DTX: Discontinuous transmission.

E endpoint: An originating or terminating device or entity. In the MSPP service, an

entry or exit point for data that streams through the gateway through an MSPP channel. For example, a Ds0 endpoint provides the terminus through which PCM data enters and leaves the gateway. An RTP endpoint provides a node through which voice data travels (framed in RTP format) on its way to the IP network.

EOS: End of sequence.

G gateway: A network point that acts as an entrance to another network, or any

device that passes packets from one network to another network in the trip across the internet.

H H.223: A protocol used to multiplex control and audio and video media on and off of

a single DS0 within a trunk.

H.245: Signaling protocol for video enabled handsets to set up and tear down calls.

H.323: An application, network, and platform independent ITU standard that enables multimedia streaming over packet-switched networks. H.323 defines call control, codec standards, and channel setup for transmitting real-time audio and video streams over connectionless networks (including packet-switched networks, intranets, and the public internet). H.323 includes the following IETF and ITU standards: H.225, H.245, H.261, G.711, G.722, G.723, G.728, G.729, Q.931, RAS, RTP (real-time transport protocol). Any H.323 client must support the H.261 video codec standard and the G.711 PCM audio codec standard.

host: The computer on which an application runs. Also used to designate a computer with full two-way access to a network such as local area network or the internet.

I IMTC: International Multimedia Telecommunications Consortium.

IP: Internet protocol; part of the TCP/IP family of protocols, it describes software that tracks the internet address of nodes, routes outgoing messages, and recognizes incoming messages.

IPR: Intellectual property right.

H.324M Interface Manual Glossary


ISDN: Integrated services digital network; a standard for providing voice and data transmission services with all-digital transmission and message-based signaling.

IVR: Interactive voice response; an application in which callers interact with a program by using recorded or synthesized voice prompts, DTMF digits, or speech recognition to query or deliver information.

J jitter: A lack of synchronization caused by varying transmission delays over a given

connection.

jitter buffer: A mechanism for receiving data over a connection with jitter and manipulating the data into a synchronous stream of data without jitter. A jitter buffer can be implemented in many ways. A simple jitter buffer can be implemented as a fixed block of allocated memory. To implement a more robust, flexible version, create a linked list of data blocks dynamically, as needed, that provides a jitter buffer of virtually unlimited size.

M MPEG: Moving Picture Experts Group. A standard for digital video and audio

compression.

MPEG-4: An ISO/IEC standard developed by MPEG. MPEG-4 became an International Standard in 1999. MPEG-4 builds on the proven success of digital television, interactive graphics applications, and interactive multimedia.

MSPP service: Media Stream Processing Protocol service. A Natural Access service that provides functions for creating and destroying media connections between endpoints established at different ends of a Fusion gateway. When enabled, these connections transfer data across the gateway from one network to another.

MUX: H.223 multiplexer

muxhandle: Operating system-specific object used to wait for a Natural Access event to be ready.

N Natural Access: NMS Communications development environment for telephony

applications.

NMS: NMS Communications Corporation.

Glossary H.324M Interface Manual


O OAM: Operations, administration, and maintenance; an industry term for system

management operations.

P PLMN: Public land mobile network.

PSTN: Public switched telephone network; the public telephone network.

R RTP: Real time transport protocol; a layer added to the internet protocol (IP) that

addresses latency problems caused when real-time interactive exchanges (such as audio data) are conducted over lines designed to carry packet-switched (connectionless) data.

S SIP: Session initiation protocol

skew: Deviation from synchronization of two or more signals.

SS7: Signaling system 7; an out-of-band signaling system that provides fast call setup using circuit-switched connections and transaction capabilities for remote database interactions.

Switching service: A Natural Access service that provides a set of functions for controlling switch connections on switching devices.

T TCP/IP: Transmission control protocol/internet protocol. A set of protocols that sets

standards for engaging in network communication between network nodes (computers or nodes connected to a network). The TCP/IP protocol suite is composed of several protocols including: IP, which handles the movement of data between host computers; TCP, which manages the movement of data between applications; and UDP, which also manages the movement of data between applications but is less complex and reliable than TCP.

TDM: Time division multiplex

transcoder: A video transcoder platform (VTP) with the NMS VTP server software installed that acts as a server to the TRC, providing a set of transcoder resources that are used to perform all video transcoding.

transcoder resource: A resource that performs video transcoding. Each video transcoder platform (VTP) provides a number of transcoder resources that is based on the processing power of the platform.

TRC: The application interface provided by the Transcoder Resource Controller module.

H.324M Interface Manual Glossary


U UII: User input indication.

V Video Access: Toolkit that allows you to develop and deploy carrier grade

applications for video communication solutions. Video Access components have a modular architecture that allows the components to be used independently or in conjunction with other Video Access components for building network systems such as video gateways and enhanced services platforms that support video applications.

video mail: Similar to a voice mail but with video.

video platform: Underlying hardware components supporting video-specific software, including CG boards with video firmware and or dedicated subsystems or servers, for example, media adaptation unit for optimized transcoding capability.

VO/VOL: Video object/video object layer as defined in the MPEG-4 specification.

VTP: An external chassis that provides the video transcoder platform on which all video transcoding occurs.


Index

B

Begin state 65

BeginCallSetup state 66

BeginMediaSetup state 67

board configuration 15

C

call flow 69, 75

call states 63

CallSetup state 66

CG boards 13

channels 21, 87

configuration 15, 19

Created state 65

E

End state 68

endpoints 21, 84

EndSession state 68

errors 79, 80

events 81

H

H324_H223_SKEW_INDICATION 30, 88

h324_h223SkewIndication 30

H324_LCD 88

H324_START_PARAMS 51, 88

H324_TERM_CAPS 36, 44, 89

H324_USER_INPUT_INDICATION 56, 89

H324_VENDORID_INDICATION 58, 90

H324_VIDEOTEMPORALSPATIALTRADEOFF_INDICATION 61, 90

h324CloseChannel 31

h324DefineMediaChannel 32

h324Delete 33

h324EndSession 34

H324EVN_* 81

h324FormatEvent 35

h324GetTermCaps 36

h324Initialize 38

h324LineErrorReporting 39

h324OLCResponse 42

h324RoundTripDelay 43

h324SetTermCaps 44

h324SetupCall 49

h324SetupMedia 50

h324Start 51

h324Stop 53

h324SubmitEvent 54

h324UserIndication 56

h324VendorIDIndication 58

h324VideoFastUpdate 60

h324VideoTemporalSpatialTradeoff 61

M

MediaSetup state 68

MSP_AUDIO_CHANNEL_PARMS 87

MSP_CHANNEL_ADDR 87

MSP_CHANNEL_PARAMETER 87

MSP_ENDPOINT_ADDR 84

MSP_ENDPOINT_PARAMETER 85

MSP_VIDEO_CHANNEL_PARMS 87

MSPP channels 21, 84

MSPP endpoints 21, 84

MUX_ENDPOINT_ADDR 85

N

NMS Video Access 7

P

performance calculations 13

port density 13

Index H.324M Interface Manual


R

reason codes 91

RTP_PAYLOAD_MAP 86

RTPRTCP_ENDPOINT_ADDR 85

RTPRTCP_ENDPOINT_PARMS 86

S

standards 9

states 63

structures 84, 88

T

terminal capabilities 25

tracing 26, 46

V

Video Access 7

62471-10

Documents

Transcript of 62471-10