/*
* sap.h
*
* Copyright (c) 1995 by DataBeam Corporation, Lexington, KY
*
* Abstract:
* This is the interface file for the class CBaseSap. This class is an abstract
* base class for objects that act as Service Access Points (SAPs) to
* external applications or the node controller.
*
* This class has two main responsibilities. First, it handles many of the
* administrative tasks that are common to all types of SAPs. These
* include handling command target registration responsibilities and
* managing the message queue. It also handles all of the primitives that
* are common between the Control SAP (CControlSAP class) and Application
* SAPs (CAppSap class). Since this class inherits from CommandTarget, it
* has the ability to communicate directly with other command targets. A
* CommandTarget object wishing to communicate with a CBaseSap object must
* register itself by passing it a CommandTarget pointer and a handle
* (typically a ConferenceID). This process is identical for both of the
* derived CBaseSap classes. Note that the CBaseSap object can handle multiple
* registered command targets at the same time.
*
* Caveats:
* None.
*
* Author:
* blp
*/
#ifndef _SAP_
#define _SAP_
/*
* include files
*/
// #include "gcmdtar.h"
#include "password.h"
#include "crost.h"
#include "arost.h"
#include "conflist.h"
#include "sesskey.h"
#include "regkey.h"
#include "regitem.h"
#include "invoklst.h"
#include "arostmsg.h"
#include "crostmsg.h"
#include "privlist.h"
#include "clists.h"
#define MSG_RANGE 0x0100
enum
{
// GCCController
GCTRLMSG_BASE = 0x2100,
// CConf
CONFMSG_BASE = 0x2200,
// CControlSAP
CSAPMSG_BASE = 0x2300,
// CControlSAP asyn direct confirm message
CSAPCONFIRM_BASE = 0x2400,
// CAppSap
ASAPMSG_BASE = 0x2500,
// NCUI
NCMSG_BASE = 0x2600,
// MCS (Node) Controller
MCTRLMSG_BASE = 0x2700,
};
LRESULT CALLBACK SapNotifyWndProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam);
typedef struct GCCAppSapMsgEx
{
GCCAppSapMsgEx(GCCMessageType);
~GCCAppSapMsgEx(void);
GCCAppSapMsg Msg;
}
GCCAppSapMsgEx, *PGCCAppSapMsgEx;
/*
* This macro defines the minimum user ID value allowed by MCS.
*/
#define MINIMUM_USER_ID_VALUE 1001
/*
* Structures and enumerations used by the CBaseSap class.
*/
//
// Class definition.
//
class CConf;
class CBaseSap : public CRefCount
{
public:
#ifdef SHIP_BUILD
CBaseSap();
#else
CBaseSap(DWORD dwStampID);
#endif
virtual ~CBaseSap(void) = 0;
GCCError ConfRosterInquire(GCCConfID, GCCAppSapMsgEx **);
GCCError AppRosterInquire(GCCConfID, GCCSessionKey *, GCCAppSapMsgEx **);
GCCError ConductorInquire(GCCConfID);
GCCError AppInvoke(GCCConfID, GCCAppProtEntityList *, GCCSimpleNodeList *, GCCRequestTag *);
BOOL IsThisNodeTopProvider(GCCConfID);
GCCNodeID GetTopProvider(GCCConfID);
virtual GCCError ConfRosterInquireConfirm(
GCCConfID,
PGCCConferenceName,
LPSTR conference_modifier,
LPWSTR pwszConfDescriptor,
CConfRoster *,
GCCResult,
GCCAppSapMsgEx **) = 0;
virtual GCCError AppRosterInquireConfirm(
GCCConfID,
CAppRosterMsg *,
GCCResult,
GCCAppSapMsgEx **) = 0;
virtual GCCError AppInvokeConfirm(
GCCConfID,
CInvokeSpecifierListContainer *,
GCCResult,
GCCRequestTag) = 0;
virtual GCCError AppInvokeIndication(
GCCConfID,
CInvokeSpecifierListContainer *,
GCCNodeID nidInvoker) = 0;
virtual GCCError AppRosterReportIndication(GCCConfID, CAppRosterMsg *) = 0;
virtual GCCError ConductorInquireConfirm(
GCCNodeID nidConductor,
GCCResult,
BOOL permission_flag,
BOOL conducted_mode,
GCCConfID) = 0;
virtual GCCError ConductorPermitGrantIndication(
GCCConfID nConfID,
UINT cGranted,
GCCNodeID *aGranted,
UINT cWaiting,
GCCNodeID *aWaiting,
BOOL fThisNodeIsGranted) = 0;
virtual GCCError ConductorAssignIndication(
GCCNodeID nidConductor,
GCCConfID conference_id) = 0;
virtual GCCError ConductorReleaseIndication(
GCCConfID conference_id) = 0;
protected:
GCCRequestTag GenerateRequestTag(void);
GCCRequestTag m_nReqTag;
HWND m_hwndNotify;
};
/*
* Comments explaining the public and protected class member functions
*/
/*
* CBaseSap();
*
* Public member function of CBaseSap.
*
* Function Description:
* This is the CBaseSap constructor. The hash list used to hold command
* target objects is initialized by this constructor.
*
* Formal Parameters:
* None.
*
* Return Value:
* None.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* ~Sap ();
*
* Public member function of CBaseSap.
*
* Function Description:
* This is the CBaseSap destructor. All message flushing and queue clearing
* is performed by the classes which inherit from CBaseSap. No work is actually
* done by this constructor.
*
* Formal Parameters:
* None.
*
* Return Value:
* None.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError RegisterConf(CConf *, GCCConfID)
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is used by command target objects (such as Conferences) in
* order to register themselves with the CBaseSap object. This is done in order
* to allow the command target object to communicate directly with the CBaseSap.
*
* Formal Parameters:
* cmdtar_object (i) Pointer to the command target object
* wishing to be registered with the CBaseSap.
* handle (i) Integer value used to index the registering
* command target in the list of command
* targets (the conference ID for confs).
*
* Return Value:
* SAP_NO_ERROR - Command target object has been
* successfully registered.
* SAP_CONFERENCE_ALREADY_REGISTERED - A command target object was
* already registered with the
* handle passed in.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError UnRegisterConf (
* UINT handle);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is used by command target objects (such as Conferences) in
* order to un-register themselves with the CBaseSap object. This is done when
* the command target object is through communicating with the CBaseSap.
*
* Formal Parameters:
* handle (i) Integer value used to index the registering
* command target in the list of command
* targets (the conference ID for confs).
*
* Return Value:
* SAP_NO_ERROR - Command target object has been
* successfully un-registered.
* SAP_NO_SUCH_CONFERENCE - No command target object was found
* registered with the handle passed in
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ConfRosterInquire(
* GCCConfID conference_id);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is used to retrieve the conference roster. This function
* just passes this request to the controller via an owner callback. The
* conference roster is delivered to the requesting command target object
* in a Conference Roster inquire confirm.
*
* Formal Parameters:
* conference_id - ID of conference for desired roster.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource allocation error occurred.
* GCC_INVALID_CONFERENCE - Conference ID is invalid.
* GCC_CONFERENCE_NOT_ESTABLISHED - Conference object has not completed
* its establishment process.
*
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError AppRosterInquire (
* GCCConfID conference_id,
* PGCCSessionKey session_key );
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is used to retrieve a list of application rosters. This
* function just passes this request to the controller via an owner
* callback. This list is delivered to the requesting SAP through an
* Application Roster inquire confirm message.
*
* Formal Parameters:
* handle (i) Integer value used to index the registering
* command target in the list of command
* targets (the conference ID for confs).
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource allocation error occurred.
* GCC_INVALID_CONFERENCE - Conference ID is invalid.
* GCC_BAD_SESSION_KEY - Session key pointer is invalid.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ConductorInquire (
* GCCConfID conference_id);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to retrieve conductorship information.
* The conductorship information is returned in the confirm.
*
* Formal Parameters:
* conference_id (i) ID of conference.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
* GCC_INVALID_CONFERENCE - Conference ID is invalid.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError AppInvoke(
* GCCConfID conference_id,
* UINT number_of_apes,
* PGCCAppProtocolEntity * ape_list,
* UINT number_of_destination_nodes,
* UserID * list_of_destination_nodes);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to invoke other applications at remote
* nodes. The request is passed on to the appropriate Conference objects.
*
* Formal Parameters:
* conference_id (i) ID of conference.
* number_of_apes (i) Number of Application Protocol Entities
* to be invoked.
* ape_list (i) List of "APE"s to be invoked.
* number_of_destination_nodes (i) Number of nodes where applications are
* to be invoked.
* list_of_destination_nodes (i) List of nodes where applications are to
* be invoked.
*
* Return Value:
* GCC_NO_ERROR - No error.
* GCC_ALLOCATION_FAILURE - Error creating an object using the
* "new" operator.
* GCC_BAD_SESSION_KEY - An invalid session key exists in
* an APE passed in.
* GCC_BAD_NUMBER_OF_APES - Number of APEs passed in as zero.
* GCC_INVALID_CONFERENCE - Conference ID is invalid.
* GCC_CONFERENCE_NOT_ESTABLISHED - Conference object has not completed
* its establishment process.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ConductorPermitAskRequest(
* GCCConfID conference_id,
* BOOL grant_permission);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to ask for certain permissions to be
* granted (or not granted) by the conductor.
*
* Formal Parameters:
* conference_id (i) ID of conference.
* grant_permission (i) Flag indicating whether asking for a certain
* permission or giving up that permission.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
* GCC_INVALID_CONFERENCE - Conference ID is invalid.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError AppRosterInquireConfirm(
* GCCConfID conference_id,
* CAppRosterMsg *roster_message,
* GCCResult result );
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to return a requested list of
* application rosters to an application or the node controller.
*
* Formal Parameters:
* conference_id (i) ID of conference.
* roster_message (i) Roster message object containing the roster data
* result (i) Result code indicating if call is successful.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ConfRosterInquireConfirm (
* GCCConfID conference_id,
* PGCCConferenceName conference_name,
* LPSTR conference_modifier,
* LPWSTR pwszConfDescriptor,
* CConfRoster *conference_roster,
* GCCResult result );
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to return a requested conference
* roster to an application or the node controller.
*
* Formal Parameters:
* conference_id (i) ID of conference.
* conference_name (i) Name of conference.
* conference_modifier (i) Name modifier for conference.
* pwszConfDescriptor (i) Desciptor string for conference.
* conference_roster (i) The conference roster being returned.
* result (i) Result code indicating result of call.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError AppInvokeConfirm(
* GCCConfID conference_id,
* CInvokeSpecifierListContainer *invoke_list,
* GCCResult result);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to confirm a call requesting application
* invocation.
*
* Formal Parameters:
* conference_id (i) ID of conference.
* invoke_list (i) List of APE attempted to be invoked.
* result (i) Result code indicating result of call.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError AppInvokeIndication (
* GCCConfID conference_id,
* CInvokeSpecifierListContainer *invoke_list,
* UserID invoking_node_id);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to send an indication to an application
* or node controller that a request for application invocation has been
* made.
*
* Formal Parameters:
* conference_id (i) ID of conference.
* invoke_list (i) List of APE's to be invoked.
* invoking_node_id (i) ID of node requesting the invoke.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ConductorInquireConfirm (
* UserID conductor_node_id,
* GCCResult result,
* BOOL permission_flag,
* BOOL conducted_mode,
* GCCConfID conference_id);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to return conductorship information
* which has been requested.
*
* Formal Parameters:
* conductor_node_id (i) Node ID of conducting node.
* result (i) Result of call.
* permission_flag (i) Flag indicating whether or not local
* node has conductorship permission.
* conducted_mode (i) Flag indicating whether or not
* conference is in conducted mode.
* conference_id (i) ID of conference.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ConductorAssignIndication (
* UserID conductor_user_id,
* GCCConfID conference_id);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to send an indication to an application
* or node controller that a request has been made to assign conductorship.
*
* Formal Parameters:
* conductor_user_id (i) Node ID of conductor.
* conference_id (i) ID of conference.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ConductorReleaseIndication (
* GCCConfID conference_id);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to send an indication to an application
* or node controller that a request for releasing conductorship has been
* made.
*
* Formal Parameters:
* conference_id (i) ID of conference.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ConductorPermitGrantIndication (
* GCCConfID conference_id,
* UINT number_granted,
* PUserID granted_node_list,
* UINT number_waiting,
* PUserID waiting_node_list,
* BOOL permission_is_granted);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to send an indication to an application
* or node controller that a request for permission from the conductor
* has been made.
*
* Formal Parameters:
* conference_id (i) ID of conference.
* number_granted (i) Number of nodes permission is requested
* for.
* granted_node_list (i) List of node ID's for nodes to be
* granted permission.
* number_waiting (i) Number of nodes waiting for permission.
* waiting_node_list (i) List of nodes waiting for permission.
* permission_is_granted (i) Flag indicating whether permission is
* granted.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ConfRosterReportIndication (
* GCCConfID conference_id,
* CConfRosterMsg *roster_message);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to indicate to applications and the
* node controller that the conference roster has been updated.
*
* Formal Parameters:
* conference_id (i) ID of conference.
* roster_message (i) Roster message object holding the updated
* roster information.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
/*
* GCCError ApplicationRosterReportIndication (
* GCCConfID conference_id,
* CAppRosterMsg *roster_message);
*
* Public member function of CBaseSap.
*
* Function Description:
* This routine is called in order to indicate to applications and the
* node controller that the list of application rosters has been updated.
*
* Formal Parameters:
* conference_id (i) ID of conference.
* roster_message (i) Roster message object holding the updated
* roster information.
*
* Return Value:
* GCC_NO_ERROR - Function completed successfully.
* GCC_ALLOCATION_FAILURE - A resource error occurred.
*
* Side Effects:
* None.
*
* Caveats:
* None.
*/
#endif