629 lines
18 KiB
C++
629 lines
18 KiB
C++
/*
|
|
* crost.h
|
|
*
|
|
* Copyright (c) 1995 by DataBeam Corporation, Lexington, KY
|
|
*
|
|
* Abstract:
|
|
* Instances of this class represent a single Conference Roster's
|
|
* information base. It encapsulates all the functionality required to
|
|
* maintain the information base which includes the ability to add new
|
|
* roster records, delete records and update records. It has the ability
|
|
* to convert its internal information base into a list of conference
|
|
* records that can be used in a GCC_ROSTER_UPDATE_INDICATION callback. It
|
|
* is also responsible for converting its internal information base into
|
|
* Conference Roster Update PDUs. Basically, this class is responsible
|
|
* for all operations that require direct access to the records contained
|
|
* in a Conference Roster.
|
|
*
|
|
* The Conference Roster class incorporates Rogue Wave list to hold the
|
|
* roster record information. Using iterators throughout the class makes
|
|
* it easy to quickly convert the information contained in the list into
|
|
* either a PDU or into a list of record pointers (for roster update
|
|
* indications back to the node controller).
|
|
*
|
|
* A Conference Roster object has the ability to serialize its roster data
|
|
* into a single contiguous memory block when it is required to send a
|
|
* message to the application interface. This serialization process is
|
|
* managed externally by the CConfRosterMsg class through calls to
|
|
* LockConferenceRoster(), UnLockConferenceRoster() and
|
|
* GetConfRoster(). When a conference roster is to be serialized, a
|
|
* call is made to LockConferenceRoster() which causes the CConfRoster
|
|
* object to increment an internal lock count and returns the number of
|
|
* bytes required to hold the complete roster update. The Conference
|
|
* Roster is then serialized into memory through a call to
|
|
* GetConfRoster(). The CConfRoster is then unlocked to allow
|
|
* it to be deleted when the free flag gets set through the
|
|
* FreeConferenceRoster() function. In the current implementation of GCC,
|
|
* FreeConferenceRoster() is not used since the CConfRosterMsg
|
|
* maintains the data used to deliver the message (see a more detailed
|
|
* description of the lock, free and unlock mechanism in the section
|
|
* describing the data containers).
|
|
*
|
|
* The Conference Roster object also is responsible for maintaining
|
|
* internal PDU data which is updated whenever a change occurs to its
|
|
* internal information base. This PDU can be affected by both local
|
|
* request or by processing incoming PDUs. Higher level objects access
|
|
* this PDU data by calling the Conference Roster's flush routine which in
|
|
* turn causes the PDU to be freed on any subsequent request that affects
|
|
* the rosters internal information base.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*
|
|
* Author:
|
|
* blp
|
|
*/
|
|
#ifndef _CONFERENCE_ROSTER_
|
|
#define _CONFERENCE_ROSTER_
|
|
|
|
#include "netaddr.h"
|
|
#include "userdata.h"
|
|
#include "clists.h"
|
|
|
|
/*
|
|
** These enumerations define the different ways the a conference roster list
|
|
** can be updated. It is used externally to inform a conference roster object
|
|
** what to of send data PDU to build.
|
|
*/
|
|
typedef enum
|
|
{
|
|
ADD_RECORD,
|
|
DELETE_RECORD,
|
|
REPLACE_RECORD,
|
|
FULL_REFRESH
|
|
}
|
|
CONF_ROSTER_UPDATE_TYPE;
|
|
|
|
/*
|
|
** This list is used to keep track of the conference participants. It is
|
|
** a list of rogue wave pointers to Unicode Strings.
|
|
*/
|
|
class CParticipantNameList : public CList
|
|
{
|
|
DEFINE_CLIST(CParticipantNameList, LPWSTR)
|
|
void DeleteList(void);
|
|
};
|
|
|
|
/*
|
|
** This is the structure used to maintain the conference roster information
|
|
** internally. Optional paramters use a NULL pointer to indicate that the
|
|
** parameter is not in use.
|
|
*/
|
|
typedef struct CONF_RECORD
|
|
{
|
|
CONF_RECORD(void);
|
|
~CONF_RECORD(void);
|
|
|
|
UserID superior_node;
|
|
NodeType node_type;
|
|
NodeProperties node_properties;
|
|
LPWSTR pwszNodeName;
|
|
CParticipantNameList *participant_name_list;
|
|
LPWSTR pwszSiteInfo;
|
|
CNetAddrListContainer *network_address_list;
|
|
LPOSTR poszAltNodeID;
|
|
CUserDataListContainer *user_data_list;
|
|
}
|
|
CONF_RECORD;
|
|
|
|
/*
|
|
** This list is used to hold the pointers to the actual conference record for
|
|
** each node in the conference. The list is indexed by the Node ID associated
|
|
** with the record.
|
|
*/
|
|
class CConfRecordList2 : public CList2
|
|
{
|
|
DEFINE_CLIST2_(CConfRecordList2, CONF_RECORD*, UserID)
|
|
void CleanList(void);
|
|
};
|
|
|
|
|
|
class CConfRoster : public CRefCount
|
|
{
|
|
public:
|
|
|
|
CConfRoster(UserID uidTopProvider, UserID uidSuperiorNode, UserID uidMime,
|
|
BOOL is_top_provider, BOOL is_local_roster, BOOL maintain_pdu_buffer);
|
|
|
|
~CConfRoster(void);
|
|
|
|
/*
|
|
* Utilities that operate on roster update PDU strucutures.
|
|
*/
|
|
void FlushRosterUpdateIndicationPDU(PNodeInformation);
|
|
GCCError BuildFullRefreshPDU(void);
|
|
GCCError ProcessRosterUpdateIndicationPDU(PNodeInformation, UserID uidSender);
|
|
|
|
/*
|
|
* Utilities used to generate a roster update message.
|
|
*/
|
|
UINT LockConferenceRoster(void);
|
|
void UnLockConferenceRoster(void);
|
|
UINT GetConfRoster(PGCCConferenceRoster *, LPBYTE memory_pointer);
|
|
/*
|
|
** Utilities that operate directly on the conference roster objects
|
|
** internal databease.
|
|
*/
|
|
GCCError AddRecord(PGCCNodeRecord, UserID);
|
|
GCCError ReplaceRecord(PGCCNodeRecord, UserID);
|
|
GCCError RemoveUserReference(UserID);
|
|
|
|
/*
|
|
** Miscelaneous utilities.
|
|
*/
|
|
void ResetConferenceRoster(void);
|
|
|
|
UINT GetNumberOfNodeRecords(void) { return m_RecordList2.GetCount(); }
|
|
BOOL Contains(UserID uidConf) { return m_RecordList2.Find(uidConf) ? TRUE : FALSE; }
|
|
BOOL HasRosterChanged(void) { return m_fRosterChanged; }
|
|
|
|
private:
|
|
|
|
/*
|
|
* Utilities used to create a roster update indication PDU.
|
|
*/
|
|
GCCError BuildRosterUpdateIndicationPDU(CONF_ROSTER_UPDATE_TYPE, UserID);
|
|
GCCError BuildSetOfRefreshesPDU(void);
|
|
GCCError BuildSetOfUpdatesPDU(UserID, CONF_ROSTER_UPDATE_TYPE);
|
|
GCCError BuildParticipantsListPDU(UserID, PParticipantsList *);
|
|
|
|
/*
|
|
* Utilities used to Free a roster update indication PDU.
|
|
*/
|
|
void FreeRosterUpdateIndicationPDU(void);
|
|
void FreeSetOfRefreshesPDU(void);
|
|
void FreeSetOfUpdatesPDU(void);
|
|
void FreeParticipantsListPDU(PParticipantsList);
|
|
void CleanUpdateRecordPDU(PSetOfNodeRecordUpdates);
|
|
|
|
/*
|
|
* Utilities used to Process roster update indications.
|
|
*/
|
|
GCCError ProcessSetOfRefreshesPDU(PSetOfNodeRecordRefreshes);
|
|
GCCError ProcessSetOfUpdatesPDU(PSetOfNodeRecordUpdates);
|
|
GCCError ProcessParticipantsListPDU(PParticipantsList, CONF_RECORD *);
|
|
|
|
/*
|
|
* Utilities used to operate on conference roster reports.
|
|
*/
|
|
void ClearRecordList(void);
|
|
|
|
void GetNodeTypeAndProperties (
|
|
NodeType pdu_node_type,
|
|
NodeProperties pdu_node_properties,
|
|
PGCCNodeType node_type,
|
|
PGCCNodeProperties node_properties);
|
|
|
|
void GetPDUNodeTypeAndProperties (
|
|
GCCNodeType node_type,
|
|
GCCNodeProperties node_properties,
|
|
PNodeType pdu_node_type,
|
|
PNodeProperties pdu_node_properties);
|
|
|
|
GCCError DeleteRecord(UserID node_id);
|
|
|
|
GCCError GetNodeSubTree(UserID, CUidList *);
|
|
|
|
private:
|
|
|
|
BOOL m_fNodesAdded;
|
|
BOOL m_fNodesRemoved;
|
|
BOOL m_fRosterChanged;
|
|
BOOL m_fTopProvider;
|
|
BOOL m_fLocalRoster;
|
|
BOOL m_fMaintainPduBuffer;
|
|
BOOL m_fPduFlushed;
|
|
UserID m_uidTopProvider;
|
|
UserID m_uidSuperiorNode;
|
|
UserID m_uidMyNodeID;
|
|
UINT m_nInstanceNumber;
|
|
UINT m_cbDataMemorySize;
|
|
NodeInformation m_NodeInformation;
|
|
CConfRecordList2 m_RecordList2;
|
|
PSetOfNodeRecordUpdates m_pNodeRecordUpdateSet;
|
|
};
|
|
|
|
#endif
|
|
|
|
/*
|
|
* CConfRoster( UserID top_provider_id,
|
|
* UserID superior_node,
|
|
* BOOL is_top_provider,
|
|
* BOOL is_local_roster,
|
|
* BOOL maintain_pdu_buffer,
|
|
*
|
|
* Public Function Description
|
|
* This is the conference roster constructor. It is responsible for
|
|
* initializing all the instance variables used by this class.
|
|
*
|
|
* Formal Parameters:
|
|
* top_provider_id - (i) The Node ID of the Top Provider
|
|
* superior_node - (i) The Node ID of the node that is the parent
|
|
* to this one. Zero for the top provider.
|
|
* is_top_provider - (i) Indicates if this is the top provider node.
|
|
* is_local_roster - (i) Indicates if this roster is a local one.
|
|
* maintain_pdu_buffer - (i) Indicates if this roster should maintain
|
|
* a PDU buffer.
|
|
*
|
|
*
|
|
* Return Value
|
|
* None.
|
|
*
|
|
* Side Effects
|
|
* None.
|
|
*
|
|
* Caveats
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* ~CConfRoster ()
|
|
*
|
|
* Public Function Description
|
|
* This is the conference roster destructor. It is responsible for
|
|
* freeing up all the internal memory used by this class.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value
|
|
* None.
|
|
*
|
|
* Side Effects
|
|
* None.
|
|
*
|
|
* Caveats
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* void FlushRosterUpdateIndicationPDU (
|
|
* PNodeInformation node_information)
|
|
*
|
|
* Public Function Description
|
|
* This routine is used to access any PDU data that might currently be
|
|
* queued inside the conference roster. PDU data is queued whenever
|
|
* a request is made to the conference roster that affects its
|
|
* internal information base.
|
|
*
|
|
* Formal Parameters:
|
|
* node_information - (o) Pointer to the PDU buffer to fill in.
|
|
*
|
|
* Return Value
|
|
* None.
|
|
*
|
|
* Side Effects
|
|
* None.
|
|
*
|
|
* Caveats
|
|
* The PDU data returned by this routine is automatically freed the next
|
|
* time a request is made to this roster object that affects its internal
|
|
* databease.
|
|
*/
|
|
|
|
/*
|
|
* GCCError BuildFullRefreshPDU (void)
|
|
*
|
|
* Public Function Description
|
|
* This routine is responsible for generating a full conference roster
|
|
* refresh PDU.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value
|
|
* GCC_NO_ERROR - No error occured.
|
|
* GCC_ALLOCATION_FAILURE - A resource error occured.
|
|
*
|
|
* Side Effects
|
|
* None.
|
|
*
|
|
* Caveats
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* GCCError ProcessRosterUpdateIndicationPDU (
|
|
* PNodeInformation node_information)
|
|
*
|
|
* Public Function Description
|
|
* This routine is responsible for processing the decoded PDU data.
|
|
* It essentially changes the conference roster objects internal database
|
|
* based on the information in the structure.
|
|
*
|
|
* Formal Parameters:
|
|
* node_information - (i) This is a pointer to a structure that
|
|
* holds the decoded PDU data.
|
|
*
|
|
* Return Value
|
|
* GCC_NO_ERROR - No error occured.
|
|
* GCC_ALLOCATION_FAILURE - A resource error occured.
|
|
*
|
|
* Side Effects
|
|
* None.
|
|
*
|
|
* Caveats
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* UINT LockConferenceRoster()
|
|
*
|
|
* Public Function Description:
|
|
* This routine is used to "lock" the "API" data for this object. This
|
|
* results in the lock count for this object being incremented. When the
|
|
* lock count transitions from 0 to 1, a calculation is made to determine
|
|
* how much memory will be needed to hold any "API" data which will
|
|
* be referenced by, but not held in, the GCCConferenceRoster structure
|
|
* which is filled in on a call to GetConfRoster. This is the
|
|
* value returned by this routine in order to allow the calling object to
|
|
* allocate that amount of memory in preparation for the call to
|
|
* GetConfRoster.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* The amount of memory, if any, which will be needed to hold "API" data
|
|
* which is referenced by, but not held in, the GCCConferenceRoster
|
|
* structure provided as an output parameter to the GetConfRoster
|
|
* call.
|
|
*
|
|
* Side Effects:
|
|
* The internal lock count is incremented.
|
|
*
|
|
* Caveats:
|
|
* The internal lock count is used in conjuction with an internal "free"
|
|
* flag as a mechanism for ensuring that this object remains in existance
|
|
* until all interested parties are through with it. The object remains
|
|
* valid (unless explicity deleted) until the lock count is zero and the
|
|
* "free" flag is set through a call to FreeConferenceRoster. This allows
|
|
* other objects to lock this object and be sure that it remains valid
|
|
* until they call UnLock which will decrement the internal lock count. A
|
|
* typical usage scenerio for this object would be: A CConfRoster
|
|
* object is constructed and then passed off to any interested parties
|
|
* through a function call. On return from the function call, the
|
|
* FreeConferenceRoster call is made which will set the internal "free"
|
|
* flag. If no other parties have locked the object with a Lock call,
|
|
* then the CConfRoster object will automatically delete itself when
|
|
* the FreeConferenceRoster call is made. If, however, any number of
|
|
* other parties has locked the object, it will remain in existence until
|
|
* each of them has unlocked the object through a call to UnLock.
|
|
*/
|
|
|
|
/*
|
|
* void UnLockConferenceRoster ();
|
|
*
|
|
* Public Function Description:
|
|
* This routine is used to "unlock" the "API" data for this object. This
|
|
* results in the lock count for this object being decremented. When the
|
|
* lock count transitions from 1 to 0, a check is made to determine
|
|
* whether the object has been freed through a call to
|
|
* FreeConferenceRoster. If so, the object will automatically delete
|
|
* itself.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* The internal lock count is decremented.
|
|
*
|
|
* Caveats:
|
|
* It is the responsibility of any party which locks an CConfRoster
|
|
* object by calling Lock to also unlock the object with a call to UnLock.
|
|
* If the party calling UnLock did not construct the CConfRoster
|
|
* object, it should assume the object to be invalid thereafter.
|
|
*/
|
|
|
|
/*
|
|
* UINT GetConfRoster(
|
|
* PGCCConferenceRoster FAR * conference_roster,
|
|
* LPSTR memory_pointer);
|
|
*
|
|
* Public Function Description:
|
|
* This routine is used to retrieve the conference roster data from
|
|
* the CConfRoster object in the "API" form of a GCCConferenceRoster.
|
|
*
|
|
* Formal Parameters:
|
|
* conference_roster (o) The GCCConferenceRoster structure to fill in.
|
|
* memory_pointer (o) The memory used to hold any data referenced by,
|
|
* but not held in, the output structure.
|
|
*
|
|
* Return Value:
|
|
* The amount of data, if any, written into the bulk memory block provided.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* GCCError AddRecord( PGCCNodeRecord conference_record,
|
|
* UserID node_id)
|
|
*
|
|
* Public Function Description:
|
|
* This routine is used to add a single nodes conference record to the
|
|
* conference roster object's internal list of records.
|
|
*
|
|
* Formal Parameters:
|
|
* conference_record (i) Pointer to the "API" record structure to add.
|
|
* node_id (i) Node ID associated with record being added.
|
|
*
|
|
* Return Value:
|
|
* GCC_NO_ERROR - No error occured.
|
|
* GCC_ALLOCATION_FAILURE - A resource error occured.
|
|
* GCC_INVALID_PARAMETER - Invalid parameter passed in.
|
|
* GCC_BAD_NETWORK_ADDRESS - Invalid network address passed in.
|
|
* GCC_BAD_NETWORK_ADDRESS_TYPE - Bad "choice" field for address
|
|
* GCC_BAD_USER_DATA - The user data passed in contained
|
|
* an invalid object key.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* GCCError RemoveRecord(UserID node_id)
|
|
*
|
|
* Public Function Description:
|
|
* This routine is used to remove a single nodes conference record from the
|
|
* conference roster object's internal list of records.
|
|
*
|
|
* Formal Parameters:
|
|
* node_id (i) Node ID of record to be removed.
|
|
*
|
|
* Return Value:
|
|
* GCC_NO_ERROR - No error occured.
|
|
* GCC_INVALID_PARAMETER - Invalid parameter passed in.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* GCCError ReplaceRecord( PGCCNodeRecord conference_record,
|
|
* UserID node_id)
|
|
*
|
|
* Public Function Description:
|
|
* This routine is used to replace a single nodes conference record in the
|
|
* conference roster object's internal list of records.
|
|
*
|
|
* Formal Parameters:
|
|
* conference_record (i) Conference record to use as the replacement.
|
|
* node_id (i) Node ID of record to be replaced.
|
|
*
|
|
* Return Value:
|
|
* GCC_NO_ERROR - No error occured.
|
|
* GCC_ALLOCATION_FAILURE - A resource error occured.
|
|
* GCC_INVALID_PARAMETER - Invalid parameter passed in.
|
|
* GCC_BAD_NETWORK_ADDRESS - Invalid network address passed in.
|
|
* GCC_BAD_NETWORK_ADDRESS_TYPE - Bad "choice" field for address
|
|
* GCC_BAD_USER_DATA - The user data passed in contained
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* GCCError RemoveUserReference (
|
|
* UserID detached_node)
|
|
*
|
|
* Public Function Description:
|
|
* This routine removes the record associated with the specified node
|
|
* id.
|
|
*
|
|
* Formal Parameters:
|
|
* detached_node (i) Node reference to remove.
|
|
*
|
|
* Return Value:
|
|
* GCC_NO_ERROR - No error occured.
|
|
* GCC_INVALID_PARAMETER - No records associated with this node
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* BOOL Contains( UserID conference_node_id )
|
|
*
|
|
* Public Function Description:
|
|
* This routine is used to determine if the specified record exists in
|
|
* the conference roster.
|
|
*
|
|
* Formal Parameters:
|
|
* conference_node_id (i) Node ID of record to check for
|
|
*
|
|
* Return Value:
|
|
* TRUE - If the record is contained in the conference roster.
|
|
* FALSE - If the record is not contained in the conference roster.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* USHORT GetNumberOfNodeRecords ();
|
|
*
|
|
* Public Function Description:
|
|
* This routine returns the total number of conference roster records
|
|
* contained in the objects conference roster record list.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* The number of records in the conference roster list.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* void ResetConferenceRoster ()
|
|
*
|
|
* Public Function Description:
|
|
* This routine takes care of resetting all the internal flags that are
|
|
* used to convey the current state of the conference roster. Should be
|
|
* called after the roster is flushed and any roster update messages have
|
|
* been delivered (after a change to the roster occurs).
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
/*
|
|
* BOOL HasRosterChanged ();
|
|
*
|
|
* Public Function Description:
|
|
* This routine informs the caller if the roster has changed since the
|
|
* last time it was reset.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* TRUE - If roster has changed
|
|
* FALSE - If roster has not changed
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
|
|
|