Defines an extension package.

DWORD mgcDefinePackage (CTAHD ctahd,
char *pkgname,
char *events)

ctahd Context handle associated with the gateway application.

pkgname Pointer to a package name. The name cannot be a name of one of the default supported MGCP packages or a previously defined package name. This string cannot include wild card characters.

events Pointer to a comma-delimited list of events and their properties according to the following syntax:

name:R:S:signaltype(duration)

• SUCCESS
• CTAERR_BAD_ARGUMENT
  The format of the events list is not valid or the events argument is NULL.
• MGCERR_BAD_EVENT_PARMS
  The events list contained an improperly formatted string.
• MGCERR_DUPLICATE_EVENT
  An entry in the events list appears more than once within the defined package.
• MGCERR_DUPLICATE_PACKAGE
  The package name conflicts with an MGCP package or a previously defined extension package.
• MGCERR_NOT_GW_HANDLE
  The specified ctahd is not the handle associated with the application.

There is no specific set of events associated with mgcDefinePackage. However, after the application defines a package, the MGCP service returns the following events to the application. The MGCP service sends these events when the call agent requests signals or events associated with the package:

• MGCEVN_SIGNAL_ON_REQUEST
  The call agent requests that the application start generating signal when it encounters a particular condition.
• MGCEVN_SIGNAL_OFF_REQUEST
  The call agent requests that the application stop generating a signal when it encounters a particular condition.
• MGCEVN_EVENT_ON_REQUEST
  The call agent requests that the application start detecting a particular event.
• MGCEVN_EVENT_OFF_REQUEST
  The call agent requests that the application stop detecting a event.

Each of these events returns a buffer containing the following structure:

typedef struct {
 DWORD size;               
 DWORD requestid;      
 char  endpointname[128]; 
 char  eventpackage[128];
 char  eventname[128]; 
 char  eventparms[128];
} MGC_EVENT_EVENT_REQUEST;

The application must invoke mgcReleaseBuffer after processing these events.

Applications invoke mgcDefinePackage to define signal and event packages not included in the default packages supported by the MGCP service. Extension packages define signals and events needed to perform specialized tasks.

Applications define the names and properties of events associated with an extension package through a comma-delimited list that uses the following syntax:

name:R:S:signaltype(duration)

This syntax provides the following information:

Syntax Entry	Description
name	Unique string used to identify the event.
R	Indicates that entry is an event that can requested by a call agent.
S	Indicates that the entry is a signal can be generated at the request of the call agent.
signaltype	When a value is entered for S, this specifies the type of signal associated with the specified event. The following strings specify the signal type: String Description OO On/Off signal. The signal is turned on until commanded by the call agent to turn it off, or vice versa. BR Brief signal. The signal has well known short duration. TO Timeout signal. The signal lasts for a given duration unless it is superseded by a new signal.
duration	Specifies the duration (in seconds) of a TO signal. For variable TO signals, specify the maximum duration that you expect.

Note: Each entry must contain either an R, an S, or both.

For example, the signal associated with a ringback on connection condition in the generic (G) MGCP package is defined in the following way:

rbk###:S:TO(180)

This definition identifies a ringback-on-connection signal (rbk###), that lasts for 180 seconds or until superseded by another signal.

After the application defines an extension package, it can register endpoints that support the package by specifying the package name in the suppackages parameter specified in the MGC_ENDPOINT_PARMS structure. However, the MGCP service does not transparently generate signals and detect events associated with extension packages. The application must perform any processing tasks associated with extension package signals or events.

For more information about standard MGCP packages and their associated events, refer to the MGCP specification defined in RFC 2705.

char  PackageName[40];
char  PackageEvents[80];

// Defines an extension package named x-Trem. 
// a1 is both an event and an on-off signal,
// a2 is a timeout signal
// a3 is an event that be only detected.
strcpy(PackageName,"x-Trem");
strcpy(PackageEvents,"a1:R:S:OO, a2:S:TO(10), a3:R");
ret = mgcDefinePackage(GWctahd, PackageName, PackageEvents);
// GWctahd = CTA Handle returned from ctaCreateContext
// for the application
if (ret != SUCCESS)
{
 printf("mgcDefinePackage returned error 0x%x\n", ret);
 return FAILURE;
}

mgcEventDone, mgcEventProcessed, mgcRegisterEndpoint, mgcReleaseBuffer, mgcReportEvent, mgcSignalDone, mgcSignalProcessed