|
|
/*
* appsap.h * * Copyright (c) 1995 by DataBeam Corporation, Lexington, KY * * Abstract: * This is the interface file for the class CAppSap. CAppSap * objects represent an external user application's Service Access * Point to GCC. This object inherits from the CBaseSap class. The CAppSap * object is instantiated when GCCCreateSap is called. From that point * forward all messages to and from that application pass through this * object. The object is explicitly deleted when GCCDeleteSap is called * or it is implicitly deleted when GCCCleanup is called by the Node * Controller. * * The primary responsibility of the CAppSap object is to route * incoming GCC primitives to their appropriate destination and to convert * the primitives into a form that is understandable to the objects * processing them. A secondary responsibility of the CAppSap object is to * maintain a queue for all indications and confirm messages that are sent * back to the registered application. Commands can be routed by the * CAppSap in one of two directions. Either to the controller or to a * specified conference. Commands that are passed to the controller, are * done so using owner callbacks. Commands that are routed to conferences * are done so using command target calls and are routed based on a * Conference ID. Note that various User Application commands will only be * routed to the CConf if that application has previously enrolled * with the conference. The CAppSap receives all confirms and indications * from either the Controller or a CConf object. These messages are * formatted into GCCMessages within the CAppSap and queued up for later * delivery. Periodically, the CAppSap's message queue is flushed by the * Controller object and the messages are delivered to the appropriate * application. * * Caveats: * The message structures that are passed back to the node controller * are defined in GCC.H. * * Author: * blp */
#ifndef _APPSAP_
#define _APPSAP_
/*
* include files */#include "igccapp.h"
#include "sap.h"
#include "clists.h"
/*
** This is the message base that is passed into any SAP objects that use this** classes Owner callback. It will typically be the controller's ** responsibility to pass this message on.*/#define APPLICATION_MESSAGE_BASE 0
/*
** Class definition*/class CAppSap : public CBaseSap, public IGCCAppSap { friend LRESULT CALLBACK SapNotifyWndProc(HWND, UINT, WPARAM, LPARAM);
public:
CAppSap(LPVOID pAppData, LPFN_APP_SAP_CB, PGCCError); ~CAppSap(void);
GCCAPI_(void) ReleaseInterface(void);
/* ------ IGCCAppSap Interface ------ */
GCCAPI AppEnroll(GCCConfID, GCCEnrollRequest *, PGCCRequestTag); GCCAPI AppInvoke(GCCConfID, GCCAppProtEntityList *, GCCSimpleNodeList *, PGCCRequestTag);
GCCAPI AppRosterInquire(GCCConfID, GCCSessionKey *, GCCAppSapMsg **); GCCAPI_(void) FreeAppSapMsg(GCCAppSapMsg *);
GCCAPI_(BOOL) IsThisNodeTopProvider(GCCConfID); GCCAPI_(GCCNodeID) GetTopProvider(GCCConfID); GCCAPI ConfRosterInquire(GCCConfID, GCCAppSapMsg **);
GCCAPI RegisterChannel(GCCConfID, GCCRegistryKey *, ChannelID); GCCAPI RegistryAssignToken(GCCConfID, GCCRegistryKey *); GCCAPI RegistrySetParameter(GCCConfID, GCCRegistryKey *, LPOSTR, GCCModificationRights); GCCAPI RegistryRetrieveEntry(GCCConfID, GCCRegistryKey *); GCCAPI RegistryDeleteEntry(GCCConfID, GCCRegistryKey *); GCCAPI RegistryMonitor(GCCConfID, BOOL fEnableDelivery, GCCRegistryKey *); GCCAPI RegistryAllocateHandle(GCCConfID, ULONG cHandles);
GCCAPI ConductorInquire(GCCConfID);
/* ------ IGCCAppSapNotify Handler ------ */
GCCError PermissionToEnrollIndication(GCCConfID, BOOL fGranted); GCCError AppEnrollConfirm(GCCAppEnrollConfirm *);
GCCError RegistryAllocateHandleConfirm(GCCConfID, ULONG cHandles, ULONG nFirstHandle, GCCResult);
GCCError RegistryConfirm(GCCConfID, GCCMessageType, CRegKeyContainer *, CRegItem *, GCCModificationRights, GCCNodeID nidOwner, GCCEntityID eidOwner, BOOL fDeliveryEnabled, GCCResult);
GCCError RegistryMonitorIndication(GCCConfID nConfID, CRegKeyContainer *pRegKey, CRegItem *pRegItem, GCCModificationRights eRights, GCCNodeID nidOwner, GCCEntityID eidOwner) { return RegistryConfirm(nConfID, GCC_MONITOR_INDICATION, pRegKey, pRegItem, eRights, nidOwner, eidOwner, FALSE, GCC_RESULT_SUCCESSFUL); }
GCCError ConfRosterInquireConfirm(GCCConfID, PGCCConferenceName, LPSTR pszConfModifier, LPWSTR pwszConfDescriptor, CConfRoster *, GCCResult, GCCAppSapMsgEx **);
GCCError AppRosterInquireConfirm(GCCConfID, CAppRosterMsg *, GCCResult, GCCAppSapMsgEx **);
GCCError AppRosterReportIndication(GCCConfID, CAppRosterMsg *);
GCCError AppInvokeConfirm(GCCConfID, CInvokeSpecifierListContainer *, GCCResult, GCCRequestTag); GCCError AppInvokeIndication(GCCConfID, CInvokeSpecifierListContainer *, GCCNodeID nidInvoker);
GCCError ConductorInquireConfirm(GCCNodeID nidConductor, GCCResult, BOOL fGranted, BOOL fConducted, GCCConfID); GCCError ConductorPermitGrantIndication(GCCConfID, UINT cGranted, GCCNodeID *aGranted, UINT cWaiting, GCCNodeID *aWaiting, BOOL fThisNodeIsGranted); GCCError ConductorAssignIndication(GCCNodeID nidConductor, GCCConfID); GCCError ConductorReleaseIndication(GCCConfID);
protected:
void NotifyProc(GCCAppSapMsgEx *pAppSapMsgEx);
private:
void PostAppSapMsg(GCCAppSapMsgEx *pAppSapMsgEx); void PurgeMessageQueue(void);
private:
LPVOID m_pAppData; // app defined user data
LPFN_APP_SAP_CB m_pfnCallback;};
/*
* Comments explaining the public and protected class member functions */
/*
* CAppSap ( * UINT owner_message_base, * UINT application_messsage_base) * * Public member function of CAppSap. * * Function Description: * This is the constructor for the CAppSap class. It initializes instance * variables and registers with the new application. * * Formal Parameters: * owner_object (i) A pointer to the owner of this object, namely * the controller. * owner_message_base (i) The message base offset for callbacks into the * controller. * application_object (i) A pointer to the application requesting service. * application_messsage_base (i) The message base offset for callbacks * to the application. * sap_handle (i) The handle registered for this SAP. * * Return Value: * None. * * Side Effects: * None. * * Caveats: * None. */
/*
* virtual ~AppSap(); * * Public member function of CAppSap. * * Function Description: * This is the destructor for the CAppSap class. It is called when the * controller marks the CAppSap to be deleted. This occurs when either * the CAppSap asks to be deleted due to an "unregister request" * issued from the client application, or when there is an error * condition in the CAppSap. * * Formal Parameters: * owner_object (i) A pointer to the owner of this object, namely * the controller. * owner_message_base (i) The message base offset for callbacks into the * controller. * application_object (i) A pointer to the application requesting service. * application_messsage_base (i) The message base offset for callbacks * to the application. * sap_handle (i) The handle registered for this SAP. * * Return Value: * GCC_NO_ERROR - No error. * GCC_ALLOCATION_FAILURE - A resource allocation error occurred. * GCC_BAD_OBJECT_KEY - An invalid object key passed in. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError AppEnroll( * GCCConfID conference_id, * PGCCSessionKey session_key, * BOOL enroll_actively, * UserID application_user_id, * BOOL is_conducting_capable, * MCSChannelType startup_channel_type, * UINT number_of_non_collapsed_caps, * PGCCNonCollapsingCapability *non_collapsed_caps_list, * UINT number_of_collapsed_caps, * PGCCApplicationCapability * collapsed_caps_list, * BOOL application_is_enrolled); * * Public member function of CAppSap. * * Function Description: * This routine is called when an application wants to enroll in a * conference. The controller is notified of the enrollment request. * * Formal Parameters: * conference_id (i) The conference identifier value. * session_key (i) Key identifying the session. * enroll_actively (i) Flag indicating whether to enroll * actively or inactively. * application_user_id (i) The application identifier value. * is_conducting_capable (i) Flag indicating whether this app * is capable of conducting. * startup_channel_type (i) The type of channel to use. * number_of_non_collapsed_caps (i) Number of non-collapsed capabilities * non_collapsed_caps_list (i) List of non-collapsed capabilities. * number_of_collapsed_caps (i) Number of collapsed capabilities. * collapsed_caps_list (i) List of collapsed capabilities. * application_is_enrolled) (i) Flag indicating whether or not the * application wishes to enroll. * * Return Value: * GCC_NO_ERROR - No error. * GCC_INVALID_MCS_USER_ID - The user ID is less than the minimum value * GCC_BAD_SESSION_KEY - A NULL session key pointer is passed in. * GCC_INVALID_CONFERENCE - The conference does not exist at this node * GCC_NO_SUCH_APPLICATION - A SAP has not been registered for this app * GCC_BAD_SESSION_KEY - An invalid session key was passed in. * GCC_INVALID_PARAMETER - The node record was not found in the list. * GCC_BAD_CAPABILITY_ID - An invalid capability ID was passed in. * GCC_ALLOCATION_FAILURE - A resource allocation error occurred. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError RegisterChannel( * GCCConfID conference_id, * PGCCRegistryKey registry_key, * ChannelID channel_id); * * Public member function of CAppSap. * * Function Description: * This routine is called when an application wishes to register a * channel. The call is routed to the appropriate conference object. * * Formal Parameters: * conference_id (i) The conference identifier value. * registry_key (i) Key identifying the session and * resource ID. * channel_id (i) ID of channel to register * * Return Value: * GCC_NO_ERROR - No error. * GCC_INVALID_CONFERENCE - Conference not found to exist. * GCC_ALLOCATION_FAILURE - A resource error occurred. * GCC_BAD_REGISTRY_KEY - The registry key is invalid. * GCC_APP_NOT_ENROLLED - Requesting application is not * enrolled with the conference. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError RegistryAssignToken( * GCCConfID conference_id, * PGCCRegistryKey registry_key); * * Public member function of CAppSap. * * Function Description: * This routine is called when an application wishes to assign a * token. The call is routed to the appropriate conference object. * * Formal Parameters: * conference_id (i) The conference identifier value. * registry_key (i) Key identifying the session and * resource ID. * * Return Value: * GCC_NO_ERROR - No error. * GCC_INVALID_CONFERENCE - Conference not found to exist. * GCC_ALLOCATION_FAILURE - A resource error occurred. * GCC_BAD_REGISTRY_KEY - The registry key is invalid. * GCC_APP_NOT_ENROLLED - Requesting application is not * enrolled with the conference. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError GCCRegistrySetParameterRequest ( * GCCConfID conference_id, * PGCCRegistryKey registry_key, * LPOSTR parameter_value, * GCCModificationRights modification_rights ); * * Public member function of CAppSap. * * Function Description: * This routine is called when an application wishes to set a * parameter. The call is routed to the appropriate conference object. * * Formal Parameters: * conference_id (i) The conference identifier value. * registry_key (i) Key identifying the session and * resource ID. * parameter_value (i) String identifying the parameter * to set. * modification_rights (i) Structure specifying the rights * to be allowed for modifying * the registry parameter. * * Return Value: * GCC_NO_ERROR - No error. * GCC_INVALID_CONFERENCE - Conference not found to exist. * GCC_ALLOCATION_FAILURE - A resource error occurred. * GCC_BAD_REGISTRY_KEY - The registry key is invalid. * GCC_APP_NOT_ENROLLED - Requesting application is not * enrolled with the conference. * GCC_INVALID_MODIFICATION_RIGHTS - The modification rights passed in * were not valid. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError GCCRegistryRetrieveEntryRequest( * GCCConfID conference_id, * PGCCRegistryKey registry_key); * * Public member function of CAppSap. * * Function Description: * This routine is called when an application wishes to retrieve a registry * entry. The call is routed to the appropriate conference object. * * Formal Parameters: * conference_id (i) The conference identifier value. * registry_key (i) Key identifying the session and * resource ID. * * Return Value: * GCC_NO_ERROR - No error. * GCC_INVALID_CONFERENCE - Conference not found to exist. * GCC_ALLOCATION_FAILURE - A resource error occurred. * GCC_BAD_REGISTRY_KEY - The registry key is invalid. * GCC_APP_NOT_ENROLLED - Requesting application is not * enrolled with the conference. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError GCCRegistryDeleteEntryRequest( * GCCConfID conference_id, * PGCCRegistryKey registry_key); * * Public member function of CAppSap. * * Function Description: * This routine is called when an application wishes to delete a registry * entry. The call is routed to the appropriate conference object. * * Formal Parameters: * conference_id (i) The conference identifier value. * registry_key (i) Key identifying the session and * resource ID. * * Return Value: * GCC_NO_ERROR - No error. * GCC_INVALID_CONFERENCE - Conference not found to exist. * GCC_ALLOCATION_FAILURE - A resource error occurred. * GCC_BAD_REGISTRY_KEY - The registry key is invalid. * GCC_APP_NOT_ENROLLED - Requesting application is not * enrolled with the conference. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError GCCRegistryMonitorRequest ( * GCCConfID conference_id, * BOOL enable_delivery, * PGCCRegistryKey registry_key ); * * Public member function of CAppSap. * * Function Description: * This routine is called when an application wishes to monitor a * particular registry entry. The call is routed to the appropriate * conference object. * * Formal Parameters: * conference_id (i) The conference identifier value. * enable_delivery (i) Flag indicating whether to turn * monitoring on or off. * registry_key (i) Key identifying the session and * resource ID. * * Return Value: * GCC_NO_ERROR - No error. * GCC_INVALID_CONFERENCE - Conference not found to exist. * GCC_ALLOCATION_FAILURE - A resource error occurred. * GCC_BAD_REGISTRY_KEY - The registry key is invalid. * GCC_APP_NOT_ENROLLED - Requesting application is not * enrolled with the conference. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError GCCRegistryAllocateHandleRequest ( * GCCConfID conference_id, * UINT number_of_handles ); * * Public member function of CAppSap. * * Function Description: * This routine is called when an application wishes to allocate one or * more handles. The call is routed to the appropriate conference object. * * Formal Parameters: * conference_id (i) The conference identifier value. * number_of_handles (i) The number of handles to allocate. * * Return Value: * GCC_NO_ERROR - No error. * GCC_INVALID_CONFERENCE - Conference not found to exist. * GCC_BAD_NUMBER_OF_HANDLES - The number of handles requested is * not within the allowable range. * GCC_ALLOCATION_FAILURE - A resource error occurred. * GCC_BAD_REGISTRY_KEY - The registry key is invalid. * GCC_APP_NOT_ENROLLED - Requesting application is not * enrolled with the conference. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError PermissionToEnrollIndication( * GCCConfID conference_id, * PGCCConferenceName conference_name, * GCCNumericString conference_modifier, * BOOL permission_is_granted); * * Public member function of CAppSap. * * Function Description: * This routine is called from a conference object when it wishes to send * an indication to the user application notifying it of a "permission to * enroll" event. This does not mean that permission to enroll is * necessarily granted to the application. It may mean that permission is * being revoked. * * Formal Parameters: * conference_id (i) The conference identifier value. * conference_name (i) The conference name. * conference_modifier (i) The confererence modifier. * permission_is_granted (i) Flag indicating whether or not * permission to enroll is granted. * * Return Value: * GCC_NO_ERROR - No error. * GCC_ALLOCATION_FAILURE - A resource allocation error occurred. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError AppEnrollConfirm(GCCAppEnrollConfirm *); * GCCConfID conference_id, * PGCCSessionKey session_key, * UINT entity_id, * UserID node_id, * GCCResult result); * * Public member function of CAppSap. * * Function Description: * This routine is called by the CConf object when it wishes * to send an enrollment confirmation to the user application. * * Formal Parameters: * conference_id (i) The conference identifier value. * session_key (i) The key identifying the session. * entity_id (i) The ID for this instance of the * application. * node_id (i) ID for this node. * result (i) Result code indicating whether or not * the enrollment was successful. * * Return Value: * GCC_NO_ERROR - No error. * GCC_ALLOCATION_FAILURE - A resource error occurred. * GCC_BAD_SESSION_KEY - The session key is invalid. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError RegistryConfirm ( * GCCConfID conference_id, * GCCMessageType message_type, * CRegKeyContainer *registry_key_data, * CRegItem *registry_item_data, * GCCModificationRights modification_rights, * UserID owner_id, * EntityID entity_id, * BOOL enable_monitoring, * GCCResult result); * * Public member function of CAppSap. * * Function Description: * This command target routine is called by the CConf object when it * wishes to send an registry confirmation to the user application. * * Formal Parameters: * conference_id (i) The conference identifier value. * message_type (i) Indicates what type of registry item * confirm this is. * registry_key_data (i) Object holding the registry key. * registry_item_data (i) Object holding the registry item. * modification_rights (i) Structure specifying the rights * to be allowed for modifying * the registry parameter. * owner_id (i) The ID of the owner of the registry item * entity_id (i) The ID for this instance of the * application. * enable_monitoring (i) Flag indicating whether the registry * item is to be monitored. * result (i) Result code indicating whether or not * the registry request was successful. * * Return Value: * GCC_NO_ERROR - No error. * GCC_ALLOCATION_FAILURE - A resource error occurred. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError RegistryMonitorIndication( * GCCConfID conference_id, * CRegKeyContainer *registry_key_data, * CRegItem *registry_item_data, * GCCModificationRights modification_rights, * UserID owner_id, * EntityID owner_entity_id); * * Public member function of CAppSap. * * Function Description: * This command target routine is called by the CConf object when it * wishes to send a Registry monitor indication to the user application. * * Formal Parameters: * conference_id (i) The conference identifier value. * registry_key_data (i) Object holding the registry key. * registry_item_data (i) Object holding the registry item. * modification_rights (i) Structure specifying the rights * to be allowed for modifying * the registry parameter. * owner_id (i) The ID of the owner of the registry item * owner_entity_id (i) The ID for the instance of the * application owning the registry. * * Return Value: * GCC_NO_ERROR - No error. * GCC_ALLOCATION_FAILURE - A resource error occurred. * * Side Effects: * None. * * Caveats: * None. */
/*
* GCCError RegistryAllocateHandleConfirm( * GCCConfID conference_id, * UINT number_of_handles, * UINT first_handle, * GCCResult result); * * Public member function of CAppSap. * * Function Description: * This routine is called by the CConf object when it wishes * to send an enrollment confirmation to the user application. * * Formal Parameters: * conference_id (i) The conference identifier value. * number_of_handles (i) The number of handles allocated. * first_handle (i) The first handle allocated. * result (i) Result code indicating whether or not * the handle allocation was successful * * Return Value: * GCC_NO_ERROR - No error. * GCC_ALLOCATION_FAILURE - A resource error occurred. * * Side Effects: * None. * * Caveats: * None. */
#endif
|
