/* * gcc.h * * Copyright (c) 1994, 1995 by DataBeam Corporation, Lexington, KY * * Abstract: * This is the interface file for the GCC DLL. This file defines all * macros, types, and functions needed to use the GCC DLL, allowing GCC * services to be accessed from user applications. * * An application requests services from GCC by making direct * calls into the DLL (this includes T.124 requests and responses). GCC * sends information back to the application through a callback (this * includes T.124 indications and confirms). The callback for the node * controller is specified in the call GCCInitialize, and the callback * for a particular application service access point is specified in the * call GCCRegisterSAP. * * During initialization, GCC allocates a timer in order to give itself * a heartbeat. If zero is passed in here the owner application (the node * controller) must take the responsibility to call GCCHeartbeat. Almost * all work is done by GCC during these clocks ticks. It is during these * clock ticks that GCC checks with MCS to see if there is any work to be * done. It is also during these clock ticks that callbacks are made to * the user applications. GCC will NEVER invoke a user callback during a * user request (allowing the user applications to not worry about * re-entrancy). Since timer events are processed during the message * loop, the developer should be aware that long periods of time away * from the message loop will result in GCC "freezing" up. * * Note that this is a "C" language interface in order to prevent any "C++" * naming conflicts between different compiler manufacturers. Therefore, * if this file is included in a module that is being compiled with a "C++" * compiler, it is necessary to use the following syntax: * * extern "C" * { * #include "gcc.h" * } * * This disables C++ name mangling on the API entry points defined within * this file. * * Author: * blp * * Caveats: * none */ #ifndef __GCC_H__ #define __GCC_H__ #include "t120type.h" /************************************************************************ * * * Generally Used Typedefs * * * *************************************************************************/ #define NM_T120_VERSION_3 (MAKELONG(0, 3)) // NM 3.0 typedef struct tagOSTR { ULONG length; LPBYTE value; } OSTR, *LPOSTR; /* ** Typedef for a GCC hex string. This typedef is used throughout GCC for ** storing variable length wide character strings with embedded NULLs. */ typedef struct { UINT hex_string_length; USHORT * hex_string; } T120HexString, GCCHexString, *PGCCHexString; /* ** Typedef for a GCC long string. This typedef is used in GCC for ** storing variable length strings of longs with embedded NULLs. */ typedef struct tagT120LongString { ULONG long_string_length; ULONG * long_string; } T120LongString, GCCLongString, *PGCCLongString; /* * TransportAddress is passed in with the ConnectRequest() call. * This address is always a pointer to an ascii string. * The TransportAddress represents a remote location. It is the TCP * address of the remote machine. * */ typedef LPSTR TransportAddress, *PTransportAddress; /* ** Typedef for a GCC Character string. This typedef is used throughout GCC for ** storing variable length, NULL terminated, single byte character strings. */ // lonchanc: we should simply use char. typedef BYTE GCCCharacter, *GCCCharacterString, **PGCCCharacterString; /* ** Typedef for a GCC Numeric string. This typedef is used throughout GCC for ** storing variable length, NULL terminated, single byte character strings. ** A single character in this string is constrained to numeric values ** ranging from "0" to "9". */ typedef LPSTR GCCNumericString, *PGCCNumericString; /* ** Typdef for GCC version which is used when registering the node controller ** or an application. */ typedef struct { USHORT major_version; USHORT minor_version; } GCCVersion, *PGCCVersion; /* ** Macros for values of Booleans passed through the GCC API. */ #define CONFERENCE_IS_LOCKED TRUE #define CONFERENCE_IS_NOT_LOCKED FALSE #define CONFERENCE_IS_LISTED TRUE #define CONFERENCE_IS_NOT_LISTED FALSE #define CONFERENCE_IS_CONDUCTIBLE TRUE #define CONFERENCE_IS_NOT_CONDUCTIBLE FALSE #define PERMISSION_IS_GRANTED TRUE #define PERMISSION_IS_NOT_GRANTED FALSE #define TIME_IS_CONFERENCE_WIDE TRUE #define TIME_IS_NOT_CONFERENCE_WIDE FALSE #define APPLICATION_IS_ENROLLED_ACTIVELY TRUE #define APPLICATION_IS_NOT_ENROLLED_ACTIVELY FALSE #define APPLICATION_IS_CONDUCTING TRUE #define APPLICATION_IS_NOT_CONDUCTING_CAPABLE FALSE #define APPLICATION_IS_ENROLLED TRUE #define APPLICATION_IS_NOT_ENROLLED FALSE #define DELIVERY_IS_ENABLED TRUE #define DELIVERY_IS_NOT_ENABLED FALSE /* ** The following enum structure typedefs are used to define the GCC Object Key. ** The GCC Object Key is used throughout GCC for things like the Application ** keys and Capability IDs. */ typedef AppletKeyType GCCObjectKeyType, *PGCCObjectKeyType;; #define GCC_OBJECT_KEY APPLET_OBJECT_KEY #define GCC_H221_NONSTANDARD_KEY APPLET_H221_NONSTD_KEY typedef struct tagT120ObjectKey { GCCObjectKeyType key_type; GCCLongString object_id; OSTR h221_non_standard_id; } T120ObjectKey, GCCObjectKey, *PGCCObjectKey; /* ** GCCNonStandardParameter ** This structure is used within the NetworkAddress typedef and ** the NetworkService typedef defined below. */ typedef struct { GCCObjectKey object_key; OSTR parameter_data; } GCCNonStandardParameter, *PGCCNonStandardParameter; /* ** GCCConferenceName ** This structure defines the conference name. In a create request, the ** conference name can include an optional unicode string but it must ** always include the simple numeric string. In a join request, either ** one can be specified. */ typedef struct { GCCNumericString numeric_string; LPWSTR text_string; /* optional */ } GCCConferenceName, GCCConfName, *PGCCConferenceName, *PGCCConfName; /* ** MCSChannelType ** Should this be defined in MCATMCS? It is used in a couple of places ** below and is explicitly defined in the T.124 specification. */ typedef AppletChannelType MCSChannelType, *PMCSChannelType; #define MCS_STATIC_CHANNEL APPLET_STATIC_CHANNEL #define MCS_DYNAMIC_MULTICAST_CHANNEL APPLET_DYNAMIC_MULTICAST_CHANNEL #define MCS_DYNAMIC_PRIVATE_CHANNEL APPLET_DYNAMIC_PRIVATE_CHANNEL #define MCS_DYNAMIC_USER_ID_CHANNEL APPLET_DYNAMIC_USER_ID_CHANNEL #define MCS_NO_CHANNEL_TYPE_SPECIFIED APPLET_NO_CHANNEL_TYPE_SPECIFIED /* ** GCCUserData ** This structure defines a user data element which is used throughout GCC. */ typedef struct { GCCObjectKey key; LPOSTR octet_string; /* optional */ } GCCUserData, *PGCCUserData; /************************************************************************ * * * Node Controller Related Typedefs * * * *************************************************************************/ /* ** GCCTerminationMethod ** The termination method is used by GCC to determine ** what action to take when all participants of a conference have ** disconnected. The conference can either be manually terminated ** by the node controller or it can terminate itself automatically when ** all the participants have left the conference. */ typedef enum { GCC_AUTOMATIC_TERMINATION_METHOD = 0, GCC_MANUAL_TERMINATION_METHOD = 1 } GCCTerminationMethod, *PGCCTerminationMethod; /* ** GCCNodeType ** GCC specified node types. These node types dictate node controller ** behavior under certain conditions. See T.124 specification for ** proper assignment based on the needs of the Node Controller. */ typedef enum { GCC_TERMINAL = 0, GCC_MULTIPORT_TERMINAL = 1, GCC_MCU = 2 } GCCNodeType, *PGCCNodeType; /* ** GCCNodeProperties ** GCC specified node properties. See T.124 specification for proper ** assignment by the Node Controller. */ typedef enum { GCC_PERIPHERAL_DEVICE = 0, GCC_MANAGEMENT_DEVICE = 1, GCC_PERIPHERAL_AND_MANAGEMENT_DEVICE = 2, GCC_NEITHER_PERIPHERAL_NOR_MANAGEMENT = 3 } GCCNodeProperties, *PGCCNodeProperties; /* ** GCCPassword ** This is the unique password specified by the convenor of the ** conference that is used by the node controller to insure conference ** security. This is also a unicode string. */ typedef struct { GCCNumericString numeric_string; LPWSTR text_string; /* optional */ } GCCPassword, *PGCCPassword; /* ** GCCChallengeResponseItem ** This structure defines what a challenge response should look like. ** Note that either a password string or response data should be passed ** but not both. */ typedef struct { GCCPassword * password_string; USHORT number_of_response_data_members; GCCUserData ** response_data_list; } GCCChallengeResponseItem, *PGCCChallengeResponseItem; typedef enum { GCC_IN_THE_CLEAR_ALGORITHM = 0, GCC_NON_STANDARD_ALGORITHM = 1 } GCCPasswordAlgorithmType, *PGCCPasswordAlgorithmType; typedef struct { GCCPasswordAlgorithmType password_algorithm_type; GCCNonStandardParameter * non_standard_algorithm; /* optional */ } GCCChallengeResponseAlgorithm, *PGCCChallengeResponseAlgorithm; typedef struct { GCCChallengeResponseAlgorithm response_algorithm; USHORT number_of_challenge_data_members; GCCUserData ** challenge_data_list; } GCCChallengeItem, *PGCCChallengeItem; typedef struct { GCCResponseTag challenge_tag; USHORT number_of_challenge_items; GCCChallengeItem ** challenge_item_list; } GCCChallengeRequest, *PGCCChallengeRequest; typedef struct { GCCResponseTag challenge_tag; GCCChallengeResponseAlgorithm response_algorithm; GCCChallengeResponseItem response_item; } GCCChallengeResponse, *PGCCChallengeResponse; typedef enum { GCC_PASSWORD_IN_THE_CLEAR = 0, GCC_PASSWORD_CHALLENGE = 1 } GCCPasswordChallengeType, *PGCCPasswordChallengeType; typedef struct { GCCPasswordChallengeType password_challenge_type; union { GCCPassword password_in_the_clear; struct { GCCChallengeRequest * challenge_request; /* optional */ GCCChallengeResponse * challenge_response; /* optional */ } challenge_request_response; } u; } GCCChallengeRequestResponse, *PGCCChallengeRequestResponse; /* ** GCCAsymmetryType ** Used in queries to determine if the calling and called node are known ** by both Node Controllers involved with the connection. */ typedef enum { GCC_ASYMMETRY_CALLER = 1, GCC_ASYMMETRY_CALLED = 2, GCC_ASYMMETRY_UNKNOWN = 3 } GCCAsymmetryType, *PGCCAsymmetryType; /* ** GCCAsymmetryIndicator ** Defines how the Node Controller sees itself when making a Query ** request or response. The random number portion of this structure is ** only used if the asymmetry_type is specified to be ** GCC_ASYMMETRY_UNKNOWN. */ typedef struct { GCCAsymmetryType asymmetry_type; unsigned long random_number; /* optional */ } GCCAsymmetryIndicator, *PGCCAsymmetryIndicator; /* ** GCCNetworkAddress ** The following block of structures defines the Network Address as defined ** by T.124. Most of these structures were taken almost verbatim from the ** ASN.1 interface file. Since I'm not really sure what most of this stuff ** is for I really didn't know how to simplify it. */ typedef struct { BOOL speech; BOOL voice_band; BOOL digital_56k; BOOL digital_64k; BOOL digital_128k; BOOL digital_192k; BOOL digital_256k; BOOL digital_320k; BOOL digital_384k; BOOL digital_512k; BOOL digital_768k; BOOL digital_1152k; BOOL digital_1472k; BOOL digital_1536k; BOOL digital_1920k; BOOL packet_mode; BOOL frame_mode; BOOL atm; } GCCTransferModes, *PGCCTransferModes; #define MAXIMUM_DIAL_STRING_LENGTH 17 typedef char GCCDialingString[MAXIMUM_DIAL_STRING_LENGTH]; typedef struct { USHORT length; USHORT * value; } GCCExtraDialingString, *PGCCExtraDialingString; typedef struct { BOOL telephony3kHz; BOOL telephony7kHz; BOOL videotelephony; BOOL videoconference; BOOL audiographic; BOOL audiovisual; BOOL multimedia; } GCCHighLayerCompatibility, *PGCCHighLayerCompatibility; typedef struct { GCCTransferModes transfer_modes; GCCDialingString international_number; GCCCharacterString sub_address_string; /* optional */ GCCExtraDialingString * extra_dialing_string; /* optional */ GCCHighLayerCompatibility * high_layer_compatibility; /* optional */ } GCCAggregatedChannelAddress, *PGCCAggregatedChannelAddress; #define MAXIMUM_NSAP_ADDRESS_SIZE 20 typedef struct { struct { UINT length; BYTE value[MAXIMUM_NSAP_ADDRESS_SIZE]; } nsap_address; LPOSTR transport_selector; /* optional */ } GCCTransportConnectionAddress, *PGCCTransportConnectionAddress; typedef enum { GCC_AGGREGATED_CHANNEL_ADDRESS = 1, GCC_TRANSPORT_CONNECTION_ADDRESS = 2, GCC_NONSTANDARD_NETWORK_ADDRESS = 3 } GCCNetworkAddressType, *PGCCNetworkAddressType; typedef struct { GCCNetworkAddressType network_address_type; union { GCCAggregatedChannelAddress aggregated_channel_address; GCCTransportConnectionAddress transport_connection_address; GCCNonStandardParameter non_standard_network_address; } u; } GCCNetworkAddress, *PGCCNetworkAddress; /* ** GCCNodeRecord ** This structure defines a single conference roster record. See the ** T.124 specification for parameter definitions. */ typedef struct { UserID node_id; UserID superior_node_id; GCCNodeType node_type; GCCNodeProperties node_properties; LPWSTR node_name; /* optional */ USHORT number_of_participants; LPWSTR * participant_name_list; /* optional */ LPWSTR site_information; /* optional */ UINT number_of_network_addresses; GCCNetworkAddress ** network_address_list; /* optional */ LPOSTR alternative_node_id; /* optional */ USHORT number_of_user_data_members; GCCUserData ** user_data_list; /* optional */ } GCCNodeRecord, *PGCCNodeRecord; /* ** GCCConferenceRoster ** This structure hold a complete conference roster. See the ** T.124 specification for parameter definitions. */ typedef struct { USHORT instance_number; BOOL nodes_were_added; BOOL nodes_were_removed; USHORT number_of_records; GCCNodeRecord ** node_record_list; } GCCConferenceRoster, *PGCCConferenceRoster, GCCConfRoster, *PGCCConfRoster; /* ** GCCConferenceDescriptor ** Definition for the conference descriptor returned in a ** conference query confirm. This holds information about the ** conferences that exists at the queried node. */ typedef struct { GCCConferenceName conference_name; GCCNumericString conference_name_modifier; /* optional */ LPWSTR conference_descriptor; /* optional */ BOOL conference_is_locked; BOOL password_in_the_clear_required; UINT number_of_network_addresses; GCCNetworkAddress ** network_address_list; /* optional */ } GCCConferenceDescriptor, *PGCCConferenceDescriptor, GCCConfDescriptor, *PGCCConfDescriptor; /* ** ConferencePrivileges ** This structure defines the list of privileges that can be assigned to ** a particular conference. */ typedef struct { BOOL terminate_is_allowed; BOOL eject_user_is_allowed; BOOL add_is_allowed; BOOL lock_unlock_is_allowed; BOOL transfer_is_allowed; } GCCConferencePrivileges, *PGCCConferencePrivileges, GCCConfPrivileges, *PGCCConfPrivileges; /************************************************************************ * * * User Application Related Typedefs * * * *************************************************************************/ /* ** GCCSessionKey ** This is a unique identifier for an application that is ** using GCC. See the T.124 for the specifics on what an application ** key should look like. A session id of zero indicates that it is ** not being used. */ typedef struct tagT120SessionKey { GCCObjectKey application_protocol_key; GCCSessionID session_id; } T120SessionKey, GCCSessionKey, *PGCCSessionKey; /* ** CapabilityType ** T.124 supports three different rules when collapsing the capabilities ** list. "Logical" keeps a count of the Application Protocol Entities ** (APEs) that have that capability, "Unsigned Minimum" collapses to the ** minimum value and "Unsigned Maximum" collapses to the maximum value. */ typedef AppletCapabilityType GCCCapabilityType, GCCCapType, *PGCCCapabilityType, *PGCCCapType; #define GCC_UNKNOWN_CAP_TYPE APPLET_UNKNOWN_CAP_TYPE #define GCC_LOGICAL_CAPABILITY APPLET_LOGICAL_CAPABILITY #define GCC_UNSIGNED_MINIMUM_CAPABILITY APPLET_UNSIGNED_MINIMUM_CAPABILITY #define GCC_UNSIGNED_MAXIMUM_CAPABILITY APPLET_UNSIGNED_MAXIMUM_CAPABILITY typedef AppletCapIDType T120CapabilityIDType, T120CapIDType, GCCCapabilityIDType, GCCCapIDType, *PGCCCapabilityIDType, *PGCCCapIDType; #define GCC_STANDARD_CAPABILITY APPLET_STANDARD_CAPABILITY #define GCC_NON_STANDARD_CAPABILITY APPLET_NONSTD_CAPABILITY /* ** CapabilityID ** T.124 supports both standard and non-standard capabilities. This ** structure is used to differentiate between the two. */ typedef struct tagT120CapID { GCCCapabilityIDType capability_id_type; GCCObjectKey non_standard_capability; ULONG standard_capability; } T120CapID, GCCCapabilityID, GCCCapID, *PGCCCapabilityID, *PGCCCapID; /* ** CapabilityClass ** This structure defines the class of capability and holds the associated ** value. Note that Logical is not necessary. Information associated with ** logical is stored in number_of_entities in the GCCApplicationCapability ** structure. */ typedef AppletCapabilityClass T120CapClass, GCCCapabilityClass, GCCCapClass, *PGCCCapabilityClass, *PGCCCapClass; /* ** GCCApplicationCapability ** This structure holds all the data associated with a single T.124 ** defined application capability. */ typedef struct tagT120AppCap { GCCCapabilityID capability_id; GCCCapabilityClass capability_class; ULONG number_of_entities; } T120AppCap, GCCApplicationCapability, GCCAppCap, *PGCCApplicationCapability, *PGCCAppCap; /* ** GCCNonCollapsingCapability */ typedef struct tagT120NonCollCap { GCCCapabilityID capability_id; LPOSTR application_data; /* optional */ } T120NonCollCap, GCCNonCollapsingCapability, GCCNonCollCap, *PGCCNonCollapsingCapability, *PGCCNonCollCap; /* ** GCCApplicationRecord ** This structure holds all the data associated with a single T.124 ** application record. See the T.124 specification for what parameters ** are optional. */ typedef struct tagT120AppRecord { GCCNodeID node_id; GCCEntityID entity_id; BOOL is_enrolled_actively; BOOL is_conducting_capable; MCSChannelType startup_channel_type; UserID application_user_id; /* optional */ ULONG number_of_non_collapsed_caps; GCCNonCollapsingCapability ** non_collapsed_caps_list; /* optional */ } T120AppRecord, GCCApplicationRecord, GCCAppRecord, *PGCCApplicationRecord, *PGCCAppRecord; /* ** GCCApplicationRoster ** This structure holds all the data associated with a single T.124 ** application roster. This includes the collapsed capabilites and ** the complete list of application records associated with an Application ** Protocol Entity (APE). */ typedef struct tagT120AppRoster { GCCSessionKey session_key; BOOL application_roster_was_changed; ULONG instance_number; BOOL nodes_were_added; BOOL nodes_were_removed; BOOL capabilities_were_changed; ULONG number_of_records; GCCApplicationRecord ** application_record_list; ULONG number_of_capabilities; GCCApplicationCapability ** capabilities_list; /* optional */ } T120AppRoster, GCCApplicationRoster, GCCAppRoster, *PGCCApplicationRoster, *PGCCAppRoster; /* ** GCCRegistryKey ** This key is used to identify a specific resource used ** by an application. This may be a particular channel or token needed ** for control purposes. */ typedef struct tagT120RegistryKey { GCCSessionKey session_key; OSTR resource_id; /* Max length is 64 */ } T120RegistryKey, GCCRegistryKey, *PGCCRegistryKey; /* ** RegistryItemType ** This enum is used to specify what type of registry item is contained ** at the specified slot in the registry. */ typedef AppletRegistryItemType GCCRegistryItemType, *PGCCRegistryItemType; #define GCC_REGISTRY_CHANNEL_ID APPLET_REGISTRY_CHANNEL_ID #define GCC_REGISTRY_TOKEN_ID APPLET_REGISTRY_TOKEN_ID #define GCC_REGISTRY_PARAMETER APPLET_REGISTRY_PARAMETER #define GCC_REGISTRY_NONE APPLET_REGISTRY_NONE /* ** GCCRegistryItem ** This structure is used to hold a single registry item. Note that the ** union supports all three registry types supported by GCC. */ typedef struct { GCCRegistryItemType item_type; // the following three fields were in a union ChannelID channel_id; TokenID token_id; OSTR parameter; /* Max length is 64 */ } T120RegistryItem, GCCRegistryItem, *PGCCRegistryItem; /* ** GCCRegistryEntryOwner ** */ typedef struct { BOOL entry_is_owned; GCCNodeID owner_node_id; GCCEntityID owner_entity_id; } T120RegistryEntryOwner, GCCRegistryEntryOwner, *PGCCRegistryEntryOwner; /* ** GCCModificationRights ** This enum is used when specifing what kind of rights a node has to ** alter the contents of a registry "parameter". */ typedef AppletModificationRights GCCModificationRights, *PGCCModificationRights; #define GCC_OWNER_RIGHTS APPLET_OWNER_RIGHTS #define GCC_SESSION_RIGHTS APPLET_SESSION_RIGHTS #define GCC_PUBLIC_RIGHTS APPLET_PUBLIC_RIGHTS #define GCC_NO_MODIFICATION_RIGHTS_SPECIFIED APPLET_NO_MODIFICATION_RIGHTS_SPECIFIED /* ** GCCAppProtocolEntity ** This structure is used to identify a protocol entity at a remote node ** when invoke is used. */ typedef struct tagT120APE { GCCSessionKey session_key; MCSChannelType startup_channel_type; BOOL must_be_invoked; ULONG number_of_expected_capabilities; GCCApplicationCapability ** expected_capabilities_list; } T120APE, GCCAppProtocolEntity, GCCApe, *PGCCAppProtocolEntity, *PGCCApe; /* ** GCCMessageType ** This section defines the messages that can be sent to the application ** through the callback facility. These messages correspond to the ** indications and confirms that are defined within T.124. */ typedef T120MessageType GCCMessageType, *PGCCMessageType; #endif // __GCC_H__