6647 lines
199 KiB
C
6647 lines
199 KiB
C
//
|
||
// Object Manager
|
||
//
|
||
|
||
#ifndef _H_OM
|
||
#define _H_OM
|
||
|
||
|
||
|
||
#include <gdc.h>
|
||
#include <ast120.h>
|
||
|
||
//
|
||
//
|
||
// CONSTANTS
|
||
//
|
||
//
|
||
|
||
|
||
|
||
//
|
||
// Function Profiles (apps)
|
||
//
|
||
#define OMFP_FIRST 0
|
||
|
||
typedef enum
|
||
{
|
||
OMFP_AL = OMFP_FIRST,
|
||
OMFP_OM,
|
||
OMFP_WB, // For old whiteboard
|
||
OMFP_MAX
|
||
}
|
||
OMFP;
|
||
|
||
|
||
//
|
||
// These are the corresponding strings (part of the protocol)
|
||
//
|
||
#define AL_FP_NAME "APP-LOAD-1.0"
|
||
#define OM_FP_NAME "OMCONTROL-1.0"
|
||
#define WB_FP_NAME "WHITEBOARD-1.0"
|
||
|
||
|
||
|
||
//
|
||
// ObMan clients
|
||
//
|
||
#define OMCLI_FIRST 0
|
||
typedef enum
|
||
{
|
||
OMCLI_AL = OMCLI_FIRST,
|
||
OMCLI_WB,
|
||
OMCLI_MAX
|
||
}
|
||
OMCLI;
|
||
|
||
|
||
//
|
||
// ObMan workset groups
|
||
//
|
||
#define OMWSG_FIRST 0
|
||
typedef enum
|
||
{
|
||
OMWSG_OM = OMWSG_FIRST,
|
||
OMWSG_AL,
|
||
OMWSG_WB,
|
||
OMWSG_MAX,
|
||
OMWSG_MAXPERCLIENT
|
||
}
|
||
OMWSG;
|
||
|
||
|
||
|
||
//
|
||
// These are the corresponding strings (part of the protocol)
|
||
//
|
||
#define OMC_WSG_NAME "OBMANCONTROL"
|
||
#define AL_WSG_NAME "APP-LOADER"
|
||
#define WB_WSG_NAME "WHITEBOARD"
|
||
|
||
|
||
//
|
||
// Specify this in place of a valid Domain handle to create/move a workset
|
||
// group outside of any calls:
|
||
//
|
||
|
||
#define OM_NO_CALL NET_INVALID_DOMAIN_ID
|
||
|
||
|
||
//
|
||
//
|
||
// SYSTEM LIMITS
|
||
//
|
||
// These are limits imposed by the architecture/design of the system.
|
||
//
|
||
//
|
||
|
||
//
|
||
// Workset group names
|
||
//
|
||
// Workset groups names are null-terminated strings, up to 32 characters
|
||
// long (including the NULL character). They are intended to be
|
||
// human-readable names, and must contain only ASCII characters between
|
||
// 0x2C and 0x5B. This range includes all uppercase characters, all digits
|
||
// and certain punctuation marks.
|
||
//
|
||
|
||
#define OM_MAX_WSGROUP_NAME_LEN 32
|
||
|
||
//
|
||
// Function Profile names
|
||
//
|
||
// Function profile names must be no longer than 16 characters (including
|
||
// the NULL character). The range of characters allowable is the same as
|
||
// for workset group names.
|
||
//
|
||
|
||
#define OM_MAX_FP_NAME_LEN 16
|
||
|
||
|
||
//
|
||
// Maximum number of changes allowed to a workset
|
||
//
|
||
// Each time a workset is changed, we increment its "generation number",
|
||
// which is used in resequencing operations. The largest size for an
|
||
// integer is 32 bits, so the maximum generation number using a convenient
|
||
// type is 2^32-1.
|
||
//
|
||
//
|
||
|
||
#define OM_MAX_GENERATION_NUMBER 0xffffffff
|
||
|
||
//
|
||
// Maximum size of an object
|
||
//
|
||
// This derives from the maximum size of a huge memory block under Windows
|
||
// (16MB less 64KB):
|
||
//
|
||
|
||
#define OM_MAX_OBJECT_SIZE ((UINT) (0x1000000 - 0x10000))
|
||
|
||
//
|
||
// Maximum update size of an object
|
||
//
|
||
// This derives from the necessity to send updates atomically in one
|
||
// network packet (see SFR 990)
|
||
//
|
||
|
||
#define OM_MAX_UPDATE_SIZE ((UINT) (0x00001f00))
|
||
|
||
//
|
||
// Maximum number of worksets per workset group
|
||
//
|
||
// This derives from the desire to make workset IDs 8-bit quantities so
|
||
// that they can fit in DC-Groupware events with a workset group handle and
|
||
// an object ID:
|
||
//
|
||
// Note: this value must be at most 255 so that certain ObMan for-loops
|
||
// don't cycle for ever.
|
||
//
|
||
|
||
#define OM_MAX_WORKSETS_PER_WSGROUP 255
|
||
|
||
//
|
||
// Maximum number of workset groups per Domain
|
||
//
|
||
// This derives from the use of the ObManControl workset group: it has one
|
||
// control workset and then one workset for each workset group in the
|
||
// Domain, so there can only be this many workset groups in a Domain:
|
||
//
|
||
// Note: this number must be at most one less that
|
||
// OM_MAX_WORKSETS_PER_WSGROUP
|
||
//
|
||
|
||
#define OM_MAX_WSGROUPS_PER_DOMAIN 64
|
||
|
||
|
||
//
|
||
// Special WSGROUPID for OMC:
|
||
//
|
||
#define WSGROUPID_OMC 0
|
||
|
||
//
|
||
//
|
||
// RETURN CODES
|
||
//
|
||
// Return codes are defined relative to the OM_BASE_RC base
|
||
//
|
||
//
|
||
|
||
enum
|
||
{
|
||
OM_RC_NO_MORE_HANDLES = OM_BASE_RC,
|
||
OM_RC_WORKSET_DOESNT_EXIST,
|
||
OM_RC_WORKSET_EXHAUSTED,
|
||
OM_RC_OBJECT_DELETED,
|
||
OM_RC_BAD_OBJECT_ID,
|
||
OM_RC_NO_SUCH_OBJECT,
|
||
OM_RC_WORKSET_LOCKED,
|
||
OM_RC_TOO_MANY_CLIENTS,
|
||
OM_RC_TOO_MANY_WSGROUPS,
|
||
OM_RC_ALREADY_REGISTERED ,
|
||
OM_RC_CANNOT_MOVE_WSGROUP,
|
||
OM_RC_LOCAL_WSGROUP,
|
||
OM_RC_ALREADY_IN_CALL,
|
||
OM_RC_NOT_ATTACHED,
|
||
OM_RC_WORKSET_ALREADY_OPEN,
|
||
OM_RC_OUT_OF_RESOURCES,
|
||
OM_RC_NETWORK_ERROR,
|
||
OM_RC_TIMED_OUT,
|
||
OM_RC_NO_PRIMARY,
|
||
OM_RC_WSGROUP_NOT_FOUND,
|
||
OM_RC_WORKSET_NOT_FOUND,
|
||
OM_RC_OBJECT_NOT_FOUND,
|
||
OM_RC_WORKSET_LOCK_GRANTED,
|
||
OM_RC_SPOILED,
|
||
OM_RC_RECEIVE_CB_NOT_FOUND,
|
||
OM_RC_OBJECT_PENDING_DELETE,
|
||
OM_RC_NO_NODES_READY,
|
||
OM_RC_BOUNCED
|
||
};
|
||
|
||
|
||
//
|
||
// Setting defaults
|
||
//
|
||
#define OM_LOCK_RETRY_COUNT_DFLT 10
|
||
|
||
#define OM_LOCK_RETRY_DELAY_DFLT 1000
|
||
|
||
#define OM_REGISTER_RETRY_COUNT_DFLT 40
|
||
|
||
#define OM_REGISTER_RETRY_DELAY_DFLT 5000
|
||
|
||
//
|
||
// This is the number of bytes we zero at the start of each object
|
||
// allocated. It must be less than DCMEM_MAX_SIZE, since ObjectAlloc
|
||
// assumes that this many bytes at the start of an object are all in the
|
||
// same segment.
|
||
//
|
||
|
||
#define OM_ZERO_OBJECT_SIZE 0x400
|
||
|
||
|
||
//
|
||
// EVENTS
|
||
// Public then Internal
|
||
//
|
||
|
||
enum
|
||
{
|
||
OM_OUT_OF_RESOURCES_IND = OM_BASE_EVENT,
|
||
OM_WSGROUP_REGISTER_CON,
|
||
OM_WSGROUP_MOVE_CON,
|
||
OM_WSGROUP_MOVE_IND,
|
||
OM_WORKSET_OPEN_CON,
|
||
OM_WORKSET_NEW_IND,
|
||
OM_WORKSET_LOCK_CON,
|
||
OM_WORKSET_UNLOCK_IND,
|
||
OM_WORKSET_CLEAR_IND,
|
||
OM_WORKSET_CLEARED_IND,
|
||
OM_OBJECT_ADD_IND,
|
||
OM_OBJECT_MOVE_IND,
|
||
OM_OBJECT_DELETE_IND,
|
||
OM_OBJECT_REPLACE_IND,
|
||
OM_OBJECT_UPDATE_IND,
|
||
OM_OBJECT_LOCK_CON,
|
||
OM_OBJECT_UNLOCK_IND,
|
||
OM_OBJECT_DELETED_IND,
|
||
OM_OBJECT_REPLACED_IND,
|
||
OM_OBJECT_UPDATED_IND,
|
||
OM_PERSON_JOINED_IND,
|
||
OM_PERSON_LEFT_IND,
|
||
OM_PERSON_DATA_CHANGED_IND,
|
||
|
||
OMINT_EVENT_LOCK_TIMEOUT,
|
||
OMINT_EVENT_SEND_QUEUE,
|
||
OMINT_EVENT_PROCESS_MESSAGE,
|
||
OMINT_EVENT_WSGROUP_REGISTER,
|
||
OMINT_EVENT_WSGROUP_MOVE,
|
||
OMINT_EVENT_WSGROUP_REGISTER_CONT,
|
||
OMINT_EVENT_WSGROUP_DEREGISTER,
|
||
OMINT_EVENT_WSGROUP_DISCARD
|
||
};
|
||
|
||
|
||
|
||
|
||
//
|
||
// Data transmission constants:
|
||
//
|
||
|
||
#define OM_NET_MAX_TRANSFER_SIZE 60000
|
||
|
||
//
|
||
// These constants identify the types of network buffer pools we use:
|
||
//
|
||
|
||
#define OM_NET_OWN_RECEIVE_POOL 1
|
||
#define OM_NET_OMC_RECEIVE_POOL 2
|
||
#define OM_NET_WSG_RECEIVE_POOL 3
|
||
#define OM_NET_SEND_POOL 4
|
||
|
||
//
|
||
// These constants are the sizes of the receive pools for each priority and
|
||
// for each type of channel we join:
|
||
//
|
||
|
||
#define OM_NET_RECEIVE_POOL_SIZE 0x00002000
|
||
|
||
#define OM_NET_OWN_RECEIVE_POOL_TOP OM_NET_RECEIVE_POOL_SIZE
|
||
#define OM_NET_OWN_RECEIVE_POOL_HIGH OM_NET_RECEIVE_POOL_SIZE
|
||
#define OM_NET_OWN_RECEIVE_POOL_MEDIUM OM_NET_RECEIVE_POOL_SIZE
|
||
#define OM_NET_OWN_RECEIVE_POOL_LOW OM_NET_RECEIVE_POOL_SIZE
|
||
|
||
#define OM_NET_OMC_RECEIVE_POOL_TOP OM_NET_RECEIVE_POOL_SIZE
|
||
#define OM_NET_OMC_RECEIVE_POOL_HIGH OM_NET_RECEIVE_POOL_SIZE
|
||
#define OM_NET_OMC_RECEIVE_POOL_MEDIUM OM_NET_RECEIVE_POOL_SIZE
|
||
#define OM_NET_OMC_RECEIVE_POOL_LOW OM_NET_RECEIVE_POOL_SIZE
|
||
|
||
#define OM_NET_WSG_RECEIVE_POOL_TOP OM_NET_RECEIVE_POOL_SIZE
|
||
#define OM_NET_WSG_RECEIVE_POOL_HIGH OM_NET_RECEIVE_POOL_SIZE
|
||
#define OM_NET_WSG_RECEIVE_POOL_MEDIUM OM_NET_RECEIVE_POOL_SIZE
|
||
#define OM_NET_WSG_RECEIVE_POOL_LOW OM_NET_RECEIVE_POOL_SIZE
|
||
|
||
#define OM_NET_SEND_POOL_SIZE 0x00004000
|
||
|
||
#define OM_NET_SEND_POOL_TOP OM_NET_SEND_POOL_SIZE
|
||
#define OM_NET_SEND_POOL_HIGH OM_NET_SEND_POOL_SIZE
|
||
#define OM_NET_SEND_POOL_MEDIUM OM_NET_SEND_POOL_SIZE
|
||
#define OM_NET_SEND_POOL_LOW OM_NET_SEND_POOL_SIZE
|
||
|
||
//
|
||
// These constants are used to decide what priority to send data transfers
|
||
// at when a Client has specified OBMAN_CHOOSES_PRIORITY for the workset:
|
||
//
|
||
#define OM_NET_HIGH_PRI_THRESHOLD 0x0100
|
||
#define OM_NET_MED_PRI_THRESHOLD 0x1000
|
||
|
||
#define OM_CHECKPOINT_WORKSET OM_MAX_WORKSETS_PER_WSGROUP
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// DATA STRUCTURES
|
||
//
|
||
// This section defines the main data structures of the ObMan API.
|
||
//
|
||
//
|
||
|
||
|
||
typedef struct tagOM_CLIENT * POM_CLIENT;
|
||
typedef struct tagOM_PRIMARY * POM_PRIMARY;
|
||
|
||
|
||
// Client objects are record pointers
|
||
typedef struct tagOM_OBJECT * POM_OBJECT;
|
||
typedef struct tagOM_WSGROUP * POM_WSGROUP;
|
||
typedef struct tagOM_DOMAIN * POM_DOMAIN;
|
||
|
||
|
||
//
|
||
// ObMan correlators
|
||
//
|
||
typedef WORD OM_CORRELATOR;
|
||
|
||
|
||
//
|
||
// Workset ID
|
||
//
|
||
// Within a workset group, worksets are identified by an 8-bit ID.
|
||
//
|
||
|
||
typedef BYTE OM_WSGROUP_HANDLE;
|
||
|
||
typedef BYTE OM_WORKSET_ID;
|
||
typedef OM_WORKSET_ID * POM_WORKSET_ID;
|
||
|
||
//
|
||
// Object structure
|
||
//
|
||
// Objects and object pointers are defined as follows:
|
||
//
|
||
|
||
typedef struct tagOM_OBJECTDATA
|
||
{
|
||
TSHR_UINT32 length; // length of the data field
|
||
BYTE data[1]; // object data, uninterpreted by ObMan;
|
||
// in reality, not 1 byte but <length>
|
||
// bytes long
|
||
}
|
||
OM_OBJECTDATA;
|
||
typedef OM_OBJECTDATA * POM_OBJECTDATA;
|
||
typedef POM_OBJECTDATA * PPOM_OBJECTDATA;
|
||
|
||
//
|
||
// Note that the maximum permitted size of an object, INCLUDING the
|
||
// <length> field, is 16MB less 64KB.
|
||
//
|
||
|
||
void __inline ValidateObjectData(POM_OBJECTDATA pData)
|
||
{
|
||
ASSERT(!IsBadWritePtr(pData, sizeof(OM_OBJECTDATA)));
|
||
ASSERT((pData->length > 0) && (pData->length < OM_MAX_OBJECT_SIZE));
|
||
}
|
||
|
||
|
||
//
|
||
// Object IDs
|
||
//
|
||
// Internally, object IDs are a combination of a network ID and a four-byte
|
||
// sequence counter:
|
||
//
|
||
|
||
typedef struct tagOM_OBJECT_ID
|
||
{
|
||
TSHR_UINT32 sequence;
|
||
NET_UID creator; // MCS user ID of node which created it
|
||
WORD pad1;
|
||
} OM_OBJECT_ID;
|
||
typedef OM_OBJECT_ID * POM_OBJECT_ID;
|
||
|
||
|
||
|
||
//
|
||
// Partitioning of the first parameter on an event for INDICATION events
|
||
//
|
||
|
||
typedef struct tagOM_EVENT_DATA16
|
||
{
|
||
OM_WSGROUP_HANDLE hWSGroup;
|
||
OM_WORKSET_ID worksetID;
|
||
}
|
||
OM_EVENT_DATA16;
|
||
typedef OM_EVENT_DATA16 * POM_EVENT_DATA16;
|
||
|
||
//
|
||
// Partitioning of the second parameter on an event for CONFIRM events
|
||
//
|
||
|
||
typedef struct tagOM_EVENT_DATA32
|
||
{
|
||
WORD result;
|
||
OM_CORRELATOR correlator;
|
||
}
|
||
OM_EVENT_DATA32;
|
||
typedef OM_EVENT_DATA32 * POM_EVENT_DATA32;
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// OBMANCONTROL
|
||
//
|
||
// This section describes the ObManControl Function Profile, as used by the
|
||
// Object Manager.
|
||
//
|
||
//
|
||
|
||
|
||
//
|
||
//
|
||
// DESCRIPTION
|
||
//
|
||
// In addition to the purely local records of workset groups, all instances
|
||
// of ObMan attached to a given Domain jointly maintain a control workset
|
||
// group containing
|
||
//
|
||
// - one workset (workset #0) listing the name, Function Profile, ID
|
||
// and MCS channel of each of the "standard" workset groups in
|
||
// the Domain, as well as the MCS user IDs of all the instances of ObMan
|
||
// in the Domain
|
||
//
|
||
// - one "registration workset" per workset group (worksets #1-#255)
|
||
// listing the MCS user IDs of the instances of ObMan which have one or
|
||
// more local Clients registered with the workset group.
|
||
//
|
||
// Creating a new workset group in a Domain causes ObMan to
|
||
//
|
||
// - add a new identification object to workset #0 and
|
||
//
|
||
// - create a new registration workset
|
||
//
|
||
// Registering with a workset group causes ObMan to
|
||
//
|
||
// - add a registration object to the appropriate registration workset.
|
||
//
|
||
|
||
//
|
||
//
|
||
// USAGE
|
||
//
|
||
// ObMan Clients can register with the ObManControl workset group, and then
|
||
// open and examine the contents of workset #0 to discover the names and
|
||
// Function Profiles of all the workset groups existing in a Domain.
|
||
//
|
||
// ObMan Clients must not attempt to lock or change the contents of this
|
||
// workset group in any way.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OBJECT DEFINITIONS
|
||
//
|
||
// This section provides the definitions for the objects contained in the
|
||
// worksets of the ObManControl workset group.
|
||
//
|
||
//
|
||
|
||
|
||
typedef BYTE OM_WSGROUP_ID;
|
||
typedef OM_WSGROUP_ID * POM_WSGROUP_ID;
|
||
|
||
|
||
//
|
||
//
|
||
// WORKSET GROUP IDENTIFICATION OBJECT
|
||
//
|
||
// This structure identifies a workset within a Domain. Objects of this
|
||
// form reside in workset #0 of ObManControl, known as the INFO workset.
|
||
//
|
||
//
|
||
|
||
#define OM_INFO_WORKSET ((OM_WORKSET_ID) 0)
|
||
|
||
//
|
||
// NET PROTOCOL
|
||
//
|
||
typedef struct
|
||
{
|
||
TSHR_UINT32 length; // size of this structure, less four
|
||
// bytes (for length field itself)
|
||
|
||
DC_ID_STAMP idStamp; // == OM_WSGINFO_ID_STAMP
|
||
|
||
NET_CHANNEL_ID channelID; // workset group's MCS channel
|
||
|
||
NET_UID creator; // NET user ID of instance of ObMan
|
||
// which created workset group
|
||
|
||
OM_WSGROUP_ID wsGroupID; // Domain-unique ID
|
||
BYTE pad1;
|
||
WORD pad2;
|
||
|
||
char functionProfile[ OM_MAX_FP_NAME_LEN ];
|
||
|
||
// function profile
|
||
|
||
char wsGroupName[ OM_MAX_WSGROUP_NAME_LEN ];
|
||
|
||
// Client-supplied name
|
||
}
|
||
OM_WSGROUP_INFO;
|
||
typedef OM_WSGROUP_INFO * POM_WSGROUP_INFO;
|
||
|
||
#define OM_WSGINFO_ID_STAMP DC_MAKE_ID_STAMP('O', 'M', 'W', 'I')
|
||
|
||
void __inline ValidateObjectDataWSGINFO(POM_WSGROUP_INFO pInfoObj)
|
||
{
|
||
ValidateObjectData((POM_OBJECTDATA)pInfoObj);
|
||
ASSERT(pInfoObj->idStamp == OM_WSGINFO_ID_STAMP);
|
||
}
|
||
|
||
|
||
//
|
||
//
|
||
// WORKSET GROUP REGISTRATION OBJECTS
|
||
//
|
||
// This structure identifies a node's usage of a workset group. These
|
||
// objects can reside in any ObManControl workset.
|
||
//
|
||
// In the case of workset #0, these objects identify a node's usage of the
|
||
// ObManControl workset group itself. Since all instances of ObMan in a
|
||
// Domain are use the ObManControl workset group, the registration objects
|
||
// in workset #0 form a complete list of all the instances of ObMan in a
|
||
// Domain.
|
||
//
|
||
//
|
||
|
||
//
|
||
// NET PROTOCOL
|
||
//
|
||
typedef struct
|
||
{
|
||
TSHR_UINT32 length; // size of this structure, less four
|
||
// bytes (for length field itself)
|
||
|
||
DC_ID_STAMP idStamp; // == OM_WSGREGREC_ID_STAMP
|
||
|
||
NET_UID userID; // user ID of ObMan to which the
|
||
// object relates
|
||
TSHR_UINT16 status; // see below for status values
|
||
|
||
TSHR_PERSON_DATA personData;
|
||
}
|
||
OM_WSGROUP_REG_REC;
|
||
typedef OM_WSGROUP_REG_REC * POM_WSGROUP_REG_REC;
|
||
|
||
#define OM_WSGREGREC_ID_STAMP DC_MAKE_ID_STAMP('O', 'M', 'R', 'R')
|
||
|
||
|
||
void __inline ValidateObjectDataWSGREGREC(POM_WSGROUP_REG_REC pRegObject)
|
||
{
|
||
ValidateObjectData((POM_OBJECTDATA)pRegObject);
|
||
ASSERT(pRegObject->idStamp == OM_WSGREGREC_ID_STAMP);
|
||
}
|
||
|
||
|
||
//
|
||
// Value for <status> field:
|
||
//
|
||
|
||
#define CATCHING_UP 1
|
||
#define READY_TO_SEND 2
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// LATE JOINER PROTOCOL
|
||
//
|
||
// If a Client registers with a workset group which already exists
|
||
// elsewhere in the Domain, that Client is considered a late joiner for
|
||
// that workset group. The protocol for bringing late joiners up to date
|
||
// is as follows (except where explicitly stated, "ObMan" means "the local
|
||
// instance of ObMan"):
|
||
//
|
||
// OVERVIEW
|
||
//
|
||
// A late-joiner node asks another "helper" node for a copy of the workset
|
||
// group. The helper node broadcasts a low-priority sweep message to all
|
||
// other nodes in the call and when it has received their replies, sends
|
||
// what it believes to be the current copy of the workset to the
|
||
// late-joiner.
|
||
//
|
||
// DETAILS
|
||
//
|
||
// At the local node, ObMan
|
||
//
|
||
// 1. locks the ObManControl workset group (one effect of this is that no
|
||
// other ObMan in the Domain will discard any workset groups it has
|
||
// local copies of)
|
||
//
|
||
// 2. examines the ObManControl workset group to determine
|
||
//
|
||
// - the MCS channel ID for the workset group
|
||
//
|
||
// - the MCS user ID of an instance of ObMan which has a copy of the
|
||
// workset group
|
||
//
|
||
// 3. requests to join the workset group channel
|
||
//
|
||
// 4. waits for the join to succeed
|
||
//
|
||
// 5. sends an OMNET_WSGROUP_SEND_REQ at high priority on the user ID
|
||
// channel of that instance of ObMan, known as the "helper"
|
||
//
|
||
// 6. broadcasts an OMNET_WORKSET_UNLOCK message at low priority to unlock
|
||
// the ObManControl workset group (on the ObManControl channel)
|
||
//
|
||
// At the helper node, ObMan
|
||
//
|
||
// 7. receives the OMNET_WSGROUP_SEND_REQ
|
||
//
|
||
// 8. marks its copy of the workset group as non-discardable
|
||
//
|
||
// 9. examines the ObManControl workset to determine the MCS user IDs
|
||
// of the remote instances of ObMan which already have copies
|
||
// of the workset group
|
||
//
|
||
// 10. broadcasts an OMNET_WSGROUP_SWEEP_REQ message on the workset group
|
||
// channel at high priority
|
||
//
|
||
// At each of the nodes queried in step 10, ObMan
|
||
//
|
||
// 11. receives the OMNET_WSGROUP_SWEEP_REQ
|
||
//
|
||
// 12. sends an OMNET_WSGROUP_SWEEP_REPLY message to the helper node at
|
||
// low priority
|
||
//
|
||
// Back at the helper node, ObMan
|
||
//
|
||
// 13. records each OMNET_WSGROUP_SWEEP_REPLY until all have been
|
||
// received*
|
||
//
|
||
// 14. sends one OMNET_WORKSET_NEW message for each workset in the workset
|
||
// group (on the late-joiners single-member channel)
|
||
//
|
||
// 15. sends an OMNET_OBJECT_ADD message for each object in each workset,
|
||
// again on the late-joiner's single member channel
|
||
//
|
||
// 16. sends an OMNET_WSGROUP_SEND_COMPLETE to the late-joiner; this
|
||
// message serves as a back marker for the late-joiner so that it
|
||
// knows when it has caught up with the state of the workset group as
|
||
// it was when it joined
|
||
//
|
||
// ASSUMPTIONS
|
||
//
|
||
// This protocol relies on the following assumptions:
|
||
//
|
||
// - The helper node receives the OMNET_WSGROUP_SEND_REQ message before
|
||
// the OMNET_WORKSET_UNLOCK message (as otherwise there is a window
|
||
// where its copy of the workset group may be discarded).
|
||
//
|
||
// This assumption is based on the fact that low-priority MCS data does
|
||
// not overtake high priority MCS data sent from the same node EVEN ON
|
||
// DIFFERENT CHANNELS.
|
||
//
|
||
// If this assumption proves invalid then either
|
||
//
|
||
// - the OMNET_WSGROUP_SEND_REQ message must be acknowledged before the
|
||
// late joiner can unlock the ObManControl workset, or
|
||
//
|
||
// - the OMNET_WSGROUP_SEND_REQ must be sent on the ObManControl
|
||
// broadcast channel, with an extra field indicating the node for which
|
||
// it is intended.
|
||
//
|
||
// - Any data received at the helper node after stage 14 begins is
|
||
// forwarded by MCS to the late-joiner.
|
||
//
|
||
// This assumption is based on the fact that the late-joiner is marked
|
||
// at the helper's MCS system as joined to the relevant channel before
|
||
// stage 14 begins. MCS guarantees that once a NET_CHANNEL_JOIN_IND has
|
||
// been received locally, the MCS system at every other node in the
|
||
// Domain is aware that the late-joiner has joined the channel.
|
||
//
|
||
// Note that in R1.1, the helper node will discover, at step 9, that there
|
||
// are no other nodes in the Domain. Therefore, steps 10-13 are eliminated
|
||
// i.e. the helper sends its copy of the workset as soon as it receives
|
||
// the request from the late-joiner.
|
||
//
|
||
// This is a major simplification and the code to implement these steps is
|
||
// not to be included in R1.1.
|
||
//
|
||
// * The glib "until all have been received" condition is actually
|
||
// difficult to implement since nodes may disappear while the helper is
|
||
// waiting. The solution to this is deferred to R2.0 (but see section on
|
||
// locking for suggested implementation).
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// WORKSET LOCKING PROTOCOL
|
||
//
|
||
// In what follows, the "state" refers to the lock state of the workset, as
|
||
// stored in the workset record.
|
||
//
|
||
// At the locking node, ObMan does the following:
|
||
//
|
||
// 1. if the state is LOCK_GRANTED, post FAILURE then quit
|
||
//
|
||
// 2. examine the workset in ObManControl which corresponds to the
|
||
// workset group containing the workset to be locked, to determine the
|
||
// IDs of the other nodes which are in using the workset group (at most
|
||
// 1 node in R1.1); put these IDs in a list of "expected respondents"
|
||
// (Note: do not include own ID in this list)
|
||
//
|
||
// 3. if this list is empty, we have succeeded so post SUCCESS and quit
|
||
//
|
||
// 4. else broadcast an OMNET_WORKSET_LOCK_REQ message on the workset
|
||
// group channel (i.e. to each of these nodes)
|
||
//
|
||
// 5. set the workset state to LOCKING and post a delayed
|
||
// OMINT_EVENT_LOCK_TIMEOUT event
|
||
//
|
||
// At the other node(s), ObMan does the following:
|
||
//
|
||
// 6. receive the OMNET_WORKSET_LOCK_REQ message from the locking node
|
||
//
|
||
// 7. examine its current workset state
|
||
//
|
||
// 8. if it is LOCK_REQUESTED and the MCS user ID of the locking node is
|
||
// less than that of the current node, goto DENY
|
||
//
|
||
// 9. else, goto GRANT
|
||
//
|
||
// DENY:
|
||
//
|
||
// 10. send an OMNET_WORKSET_LOCK_DENY message to the locking node
|
||
//
|
||
// GRANT:
|
||
//
|
||
// 11. if the state if LOCKING, then we are giving the lock to a higher
|
||
// "priority" ObMan even though we wanted it ourselves, so post
|
||
// FAILURE
|
||
// locally (continue to 12)
|
||
//
|
||
// 12. set the state to LOCK_GRANTED
|
||
//
|
||
// 13. send an OMNET_WORKSET_LOCK_GRANT message to the locking node
|
||
//
|
||
// Back at the locking node, one of the following happens:
|
||
//
|
||
// ObMan receives an OMNET_WORKSET_LOCK_GRANT message
|
||
//
|
||
// it then deletes the ID of the node which sent it from the list of
|
||
// expected respondents
|
||
//
|
||
// if this list is now empty, all nodes have replied so post SUCCESS
|
||
// to Client
|
||
//
|
||
// OR
|
||
//
|
||
// ObMan receives an OMNET_WORKSET_LOCK_DENY message
|
||
//
|
||
// if the state is LOCKING, set it to READY, post FAILURE and quit
|
||
//
|
||
// if the state is anything else, this reply has come too late
|
||
// (we've timed out) so ignore it
|
||
//
|
||
// OR
|
||
//
|
||
// ObMan receives the OMINT_EVENT_LOCK_TIMEOUT event
|
||
//
|
||
// if the state is not LOCKING, the lock has succeeded so ignore the
|
||
// timeout
|
||
//
|
||
// otherwise, ObMan checks the ObManControl workset as in step 2 to
|
||
// see if any nodes still on the expected respondents list have in
|
||
// fact disappeared; if so post SUCCESS
|
||
//
|
||
// else post FAILURE.
|
||
//
|
||
//
|
||
//
|
||
// The state machine for the locking process is as follows (R1.1 version):
|
||
//
|
||
// |---------+-----------+---------+--------------|
|
||
// |UNLOCKED | LOCKING | LOCKED | LOCK_GRANTED |
|
||
// | 1 | 2 | 3 | 4 |
|
||
// |---------+-----------+---------+--------------|
|
||
// WorksetLock() |broadcast| FAIL | FAIL | FAIL |
|
||
// |LOCK_REQ,| | | |
|
||
// | ->2 | | | |
|
||
// |---------+-----------+---------+--------------|
|
||
// WorksetUnlock() | X |broadcast UNLOCK, ->1| X |
|
||
// |---------+-----------+---------+--------------|
|
||
// OMNET_WORKSET_LOCK_REQ |reply |compare |reply | - |
|
||
// |GRANT, |MCS IDs: |DENY | |
|
||
// | ->4 |if we're | | (in R1.1, |
|
||
// | |greater, | | this should |
|
||
// | |reply DENY | | be an error) |
|
||
// | |else reply | | |
|
||
// | |GRANT, ->4 | | |
|
||
// |---------+-----------+---------+--------------|
|
||
// OMNET_WORKSET_LOCK_GRANT| - |SUCCESS, | - | - |
|
||
// | | ->3 | | |
|
||
// |---------+-----------+---------+--------------|
|
||
// OMNET_WORKSET_LOCK_DENY | - |FAIL, ->1 | X | - |
|
||
// | | | | |
|
||
// |---------+-----------+---------+--------------|
|
||
// OMINT_EVENT_LOCK_TIMEOUT | - |if other | - | - |
|
||
// | |box gone, | | |
|
||
// | |SUCCESS, | | |
|
||
// | |->3, else | | |
|
||
// | |FAIL, ->1 | | |
|
||
// |---------+-----------+---------+--------------|
|
||
// OMNET_WORKSET_UNLOCK | - | - | X | ->1 |
|
||
// |---------+-----------+---------+--------------|
|
||
//
|
||
//
|
||
// where 'X' indicates an error condition and '-' indicates that the event
|
||
// or message is ignored.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// NOTES FOR R2.0 WORKSET LOCKING
|
||
//
|
||
// 1. If A tries to lock a workset and B grants the lock but C denies it,
|
||
// B will think that A has the lock. A has to broadcast an unlock,
|
||
// or else B has to realise that the conflict will be resolved in
|
||
// favour of C over A.
|
||
//
|
||
//
|
||
|
||
|
||
//
|
||
//
|
||
// DATA PROPAGATION and FLOW NOTIFICATION PROTOCOL
|
||
//
|
||
// When a local Client adds an object to a workset, or replaces or updates
|
||
// an existing object in a workset, ObMan broadcasts an appropriate
|
||
// OMNET_... message on the workset group channel.
|
||
//
|
||
// This header message identifies the object and the type of operation to
|
||
// be performed. It also includes a correlator value and the total size of
|
||
// the data to be sent in the following data packets.
|
||
//
|
||
// After sending the header, ObMan broadcasts one or more
|
||
// OMNET_GENERIC_DATA packets on the same channel. These packets, which
|
||
// are of arbitrary size, all contain the same correlator value as was
|
||
// included in the header packet.
|
||
//
|
||
// No sequence numbers are included as MCS guarantees that data packets
|
||
// sent at the same priority on the same channel from the same node will
|
||
// arrive at all other nodes in the sequence in which they were sent.
|
||
//
|
||
// It is the responsibility of the receiving node to detect when all data
|
||
// packets have arrived and then to insert, update or replace the object in
|
||
// the local copy of the workset.
|
||
//
|
||
// In addition, the receiving node, on receipt of EACH data packet sends a
|
||
// data acknowledgment message (OMNET_DATA_ACK) to the sending node (on its
|
||
// single-user channel), indicating the number of bytes received in that
|
||
// data packet.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// STANDARD OPERATION BROADCAST PROTOCOL
|
||
//
|
||
// When a local Client deletes or moves an object in a workset, or clears
|
||
// or creates a workset, ObMan broadcasts a single uncorrelated operation
|
||
// packet on the workset group channel.
|
||
//
|
||
// It is the responsibility of the receiving node to implement the
|
||
// operation locally.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OPERATION SEQUENCING AND RESEQUENCING
|
||
//
|
||
// In order to consistently sequence operations which may arrive in
|
||
// different sequences at different nodes, each operation carries with it
|
||
// enough information for ObMan to reconstruct the workset, at each node,
|
||
// as if all the operations on it had arrived in the same sequence.
|
||
//
|
||
// To do this, all operations are assigned a sequence stamp before being
|
||
// broadcast. When ObMan receives an operation from the network, it
|
||
// compares its stamp to various stamps it maintains locally. Whether and
|
||
// how to perform the operation locally is determined on the basis of these
|
||
// comparisons, according to the rules defined below.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// SEQUENCE STAMPS AND THE WORKSET GENERATION NUMBER
|
||
//
|
||
// The sequencing order must be a globally consistent method of ordering
|
||
// events ("global" here refers to geographical distribution of all nodes
|
||
// operating on a given workset; it is not necessary that events be
|
||
// sequenced across different worksets, since operations on separate
|
||
// worksets can never interfere).
|
||
//
|
||
// We define an ObMan sequence stamp to be a combination of the workset
|
||
// generation number and the node id.
|
||
//
|
||
// The node ID is the user ID allocated by the MCS subsystem to the ObMan
|
||
// task and is therefore unique within a Domain.
|
||
//
|
||
// The workset generation number
|
||
//
|
||
// - is set to zero when the workset is created
|
||
//
|
||
// - is incremented each time ObMan performs an operation on behalf
|
||
// of a local Client
|
||
//
|
||
// - is, whenever an operation arrives from the network, set to the
|
||
// greater of its existing local value and the value in the
|
||
// operation's sequence stamp.
|
||
//
|
||
// The ordering of sequence stamps is defined as follows (notation: stampX
|
||
// = wsetGenX.nodeX):
|
||
//
|
||
// - if wsetGen1 < wsetGen2, then stamp1 < ("is lower than") stamp2
|
||
//
|
||
// - elsif wsetGen1 = wsetGen2, then
|
||
//
|
||
// - if node1 < node2, then stamp1 < stamp2
|
||
//
|
||
// - else stamp2 < stamp1.
|
||
//
|
||
// For the purposes of sequencing the different types of operations, ObMan
|
||
// maintains
|
||
//
|
||
// - one sequence stamp per workset:
|
||
//
|
||
// - the last 'time' it was cleared (the clear stamp)
|
||
//
|
||
// - four sequence stamps per object:
|
||
//
|
||
// - the 'time' the object was added (the addition stamp)
|
||
//
|
||
// - the 'time' the object was last moved (the position stamp)
|
||
//
|
||
// - the 'time' the object was last updated (the update stamp)
|
||
//
|
||
// - the 'time' the object was last replace (the replace stamp; in
|
||
// reality, only one of the update/replace stamps is required for
|
||
// sequencing but both are needed for optimum spoiling).
|
||
//
|
||
// The initial values of the position, update and replace stamps are set to
|
||
// the value of the addition stamp.
|
||
//
|
||
// The initial value of the clear stamp is set to <0.ID> where ID is the ID
|
||
// of the node which created the workset.
|
||
//
|
||
// In addition, each object has a position field (either FIRST or LAST in
|
||
// R1.1) which indicates where the object was most recently positioned i.e.
|
||
// it is set when the object is added and then each time the object is
|
||
// moved within the workset.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// SEQUENCING PROTOCOLS
|
||
//
|
||
// The treatment of each type of operation is now considered in turn.
|
||
//
|
||
// 1. Operations on unknown objects or worksets
|
||
//
|
||
// ObMan may at any time receive operations on objects or worksets which do
|
||
// not exist locally. These operations may be on objects or worksets which
|
||
//
|
||
// - this node has not yet heard of, or
|
||
//
|
||
// - have been deleted.
|
||
//
|
||
// Operations on the first kind need to be delayed and reprocessed at a
|
||
// later time. Operations on the second kind can be thrown away (note that
|
||
// there are no workset operations of this kind as once opened, worksets
|
||
// are never deleted in the lifetime of the workset group).
|
||
//
|
||
// To differentiate between the two, ObMan keeps a record of deleted
|
||
// objects. When an operation on a deleted object arrives, it is
|
||
// discarded. When an operation arrives for an object which is not in
|
||
// either the active object list or the deleted object list, ObMan bounces
|
||
// the event from the network layer back to its event loop, with a suitable
|
||
// delay, and attempts to process it later.
|
||
//
|
||
// For simplicity, the deleted object list is implemented by flagging
|
||
// deleted objects as such and leaving them in the main list of objects
|
||
// (i.e. the workset), rather than moving them to a separate list. The
|
||
// object data is, however, discarded; only the object record needs to be
|
||
// kept.
|
||
//
|
||
// Events from the network layer referring to operations on unknown
|
||
// worksets are automatically bounced back onto ObMan's event queue.
|
||
//
|
||
// 2. Adding an object
|
||
//
|
||
// If ObMan receives an Add operation for an object which it has already
|
||
// added to a workset (i.e. the object IDs are the same), it discards the
|
||
// operation.
|
||
//
|
||
// This normally will not happen since each object is added by only one
|
||
// node, and no node adds an object with the same ID twice.
|
||
//
|
||
// However, while a late-joiner is catching up with the contents of a
|
||
// workset, it is possible that it will receive notification of a
|
||
// particular object from both
|
||
//
|
||
// - the node which added the object
|
||
//
|
||
// - the helper node which is sending it the entire workset
|
||
// contents.
|
||
//
|
||
// Therefore, the late-joiner checks object IDs as they arrive and discards
|
||
// them if they have already been received. Note that since the
|
||
// positioning algorithm presented below will position each occurrence of
|
||
// the object in adjacent positions, checking for ID clashes is a simple
|
||
// matter, performed after the correct position has been found.
|
||
//
|
||
// 3. Positioning (adding or moving) an object in a workset
|
||
//
|
||
// The desired sequence of objects in a workset is defined to be one
|
||
// whereby
|
||
//
|
||
// - all the objects which were positioned at the start of a workset (FIRST
|
||
// objects) are before all the objects which were positioned at the end
|
||
// of a workset (LAST objects)
|
||
//
|
||
// - the position stamps of all the FIRST objects decrease monotonically
|
||
// from the start of the workset forward
|
||
//
|
||
// - the position stamps of all the LAST objects decrease monotonically
|
||
// from the end of the workset backward.
|
||
//
|
||
// Accordingly, the protocol when positioning an object at the start of a
|
||
// workset is as follows (instructions for end-of-workset positioning in
|
||
// brackets):
|
||
//
|
||
// ObMan searches forward (back) from the start (end) of the workset until
|
||
// if finds an object which either
|
||
//
|
||
// - is not a FIRST (LAST) object, or
|
||
//
|
||
// - has a lower (lower) position stamp
|
||
//
|
||
// ObMan inserts the new/moved object before (after) this object.
|
||
//
|
||
// 4. Clearing a workset
|
||
//
|
||
// On receiving a Clear operation, ObMan searches through the workset and
|
||
// deletes all objects which have an addition stamp lower than the clear
|
||
// operation's stamp.
|
||
//
|
||
// On receiving an addition to a workset, ObMan discards the operation if
|
||
// its stamp is lower than the workset's clear stamp.
|
||
//
|
||
// 5. Updating an object
|
||
//
|
||
// On receiving an Update operation, ObMan compares its stamp with the
|
||
// object's update and replace stamps. If the operation's stamp is higher
|
||
// than both, the operation is performed; otherwise, the operation is
|
||
// discarded (since an Update is superceded either by a later Replace or by
|
||
// a later Update).
|
||
//
|
||
// 6. Replacing an object
|
||
//
|
||
// On receiving a Replace operation, ObMan compares its stamp with the
|
||
// object's replace stamp. If the operation's stamp is higher, the
|
||
// operation is performed; otherwise, the operation is discarded (since a
|
||
// Replace is superceded by a later Replace but not by a later Update).
|
||
//
|
||
// 7. Deleting an object
|
||
//
|
||
// By definition, a Delete is the last operation that should be performed
|
||
// on an object. Delete operations are therefore processed immediately by
|
||
// setting the <deleted> flag in the object record to TRUE.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OPERATION RESEQUENCING - SUMMARY
|
||
//
|
||
// In summary, therefore,
|
||
//
|
||
// - all object operations are discarded if object found on the deleted
|
||
// object queue
|
||
//
|
||
// - Add operations are discarded if they refer to an existing object.
|
||
//
|
||
// - Add/Clear operations are requeued if the workset is not present
|
||
// locally
|
||
//
|
||
// - Update/Replace/Move/Delete operations are requeued if the object or
|
||
// workset is not present locally
|
||
//
|
||
// - Update operations are discarded if an Update or a Replace with a later
|
||
// sequence stamp has already been received.
|
||
//
|
||
// - Replace operations are discarded if a Replace with a later sequence
|
||
// stamp has already been received.
|
||
//
|
||
// By default, all operations are performed.
|
||
//
|
||
//
|
||
|
||
|
||
//
|
||
//
|
||
// OBJECT IDS
|
||
//
|
||
// Object IDs are structures which identify an object within a workset.
|
||
// For a given workset, they are unique throughout the Domain.
|
||
//
|
||
// To ensure uniqueness, the MCS user ID is used as a (two-byte) prefix to
|
||
// a four-byte sequence number generated locally, on a per workset basis.
|
||
//
|
||
// Workset groups can exist independently of a Domain, and therefore
|
||
// potentially before ObMan has been allocated an MCS user ID. When
|
||
// allocating object IDs in this situation, ObMan uses zero (0) as the
|
||
// prefix to the sequence number.
|
||
//
|
||
// If that workset group is subsequently moved into a Domain, for all
|
||
// subsequent ID allocations ObMan uses its MCS user ID for that Domain as
|
||
// the prefix. Other instances of ObMan may also start adding objects to
|
||
// the worksets in the group at this point, and they too use their MCS user
|
||
// IDs as the object ID prefix. Uniqueness is preserved by the MCS
|
||
// guarantee that zero is never a valid user ID, so no post-share generated
|
||
// ID can conflict with a pre-share generated ID.
|
||
//
|
||
//
|
||
|
||
|
||
//
|
||
//
|
||
// SEQUENCE STAMPS
|
||
//
|
||
// Sequence stamps define a Domain-wide ordering for operations. They are
|
||
// used to correctly execute operations which may arrive at a node in an
|
||
// indeterminate order.
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_SEQUENCE_STAMP
|
||
{
|
||
TSHR_UINT32 genNumber; // the workset generation number
|
||
// which was current when the
|
||
// stamp was issued
|
||
NET_UID userID; // the MCS user ID for ObMan at
|
||
// the node which issued it
|
||
|
||
WORD pad1;
|
||
} OM_SEQUENCE_STAMP;
|
||
|
||
typedef OM_SEQUENCE_STAMP * POM_SEQUENCE_STAMP;
|
||
|
||
|
||
//
|
||
//
|
||
// OBJECT POSITION STAMPS
|
||
//
|
||
// When an object is added to or moved within a workset, it is important to
|
||
// know where it has been added. Therefore, Add and Move operations
|
||
// include within them a position field, with the following type:
|
||
//
|
||
//
|
||
|
||
typedef BYTE OM_POSITION;
|
||
|
||
//
|
||
// Possible values for an OM_POSITION variable:
|
||
//
|
||
|
||
#define LAST 1
|
||
#define FIRST 2
|
||
#define BEFORE 3
|
||
#define AFTER 4
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// SEQUENCE STAMP MANIPULATION
|
||
//
|
||
// These macro manipulate sequence stamps.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// STAMP_IS_LOWER(stamp1, stamp2)
|
||
//
|
||
// This macro compares one sequence stamp with another. It evaluates to
|
||
// TRUE if the first stamp is lower than the second.
|
||
//
|
||
//
|
||
|
||
#define STAMP_IS_LOWER(stamp1, stamp2) \
|
||
\
|
||
(((stamp1).genNumber < (stamp2).genNumber) ? \
|
||
TRUE : \
|
||
(((stamp1).genNumber == (stamp2).genNumber) \
|
||
&& \
|
||
((stamp1).userID < (stamp2).userID)))
|
||
|
||
|
||
//
|
||
//
|
||
// SET_NULL_SEQ_STAMP(stamp)
|
||
//
|
||
// This macro sets the sequence stamp <stamp> to NULL.
|
||
//
|
||
//
|
||
|
||
#define SET_NULL_SEQ_STAMP(stamp) \
|
||
\
|
||
(stamp).userID = 0; \
|
||
(stamp).genNumber = 0
|
||
|
||
//
|
||
//
|
||
// SEQ_STAMP_IS_NULL(stamp)
|
||
//
|
||
// This macro evaluates to TRUE if the sequence stamp <stamp> is a NULL
|
||
// sequence stamp.
|
||
//
|
||
//
|
||
|
||
#define SEQ_STAMP_IS_NULL(stamp) \
|
||
\
|
||
((stamp.userID == 0) && (stamp.genNumber == 0))
|
||
|
||
//
|
||
//
|
||
// COPY_SEQ_STAMP(stamp1, stamp2)
|
||
//
|
||
// This macro sets the value of the first sequence stamp to that of the
|
||
// second.
|
||
//
|
||
//
|
||
|
||
#define COPY_SEQ_STAMP(stamp1, stamp2) \
|
||
\
|
||
(stamp1).userID = (stamp2).userID; \
|
||
(stamp1).genNumber = (stamp2).genNumber
|
||
|
||
|
||
//
|
||
//
|
||
// MESSAGE FORMATS
|
||
//
|
||
// This section describes the formats of the messages sent between
|
||
// different instances of ObMan.
|
||
//
|
||
// The names of these messages are prefixed OMNET_...
|
||
//
|
||
// These events have the following format:
|
||
//
|
||
// typedef struct
|
||
// {
|
||
// OMNET_PKT_HEADER header;
|
||
// :
|
||
// : [various event specific fields]
|
||
// :
|
||
//
|
||
// } OMNET_...
|
||
//
|
||
// The OMNET_PKT_HEADER type is defined below.
|
||
//
|
||
//
|
||
|
||
typedef TSHR_UINT16 OMNET_MESSAGE_TYPE;
|
||
|
||
typedef struct tagOMNET_PKT_HEADER
|
||
{
|
||
NET_UID sender; // MCS user ID of sender
|
||
OMNET_MESSAGE_TYPE messageType; // == OMNET_...
|
||
}
|
||
OMNET_PKT_HEADER;
|
||
typedef OMNET_PKT_HEADER * POMNET_PKT_HEADER;
|
||
|
||
//
|
||
// Possible values for a OMNET_MESSAGE_TYPE variable:
|
||
//
|
||
|
||
#define OMNET_NULL_MESSAGE ((OMNET_MESSAGE_TYPE) 0x00)
|
||
|
||
#define OMNET_HELLO ((OMNET_MESSAGE_TYPE) 0x0A)
|
||
#define OMNET_WELCOME ((OMNET_MESSAGE_TYPE) 0x0B)
|
||
|
||
#define OMNET_LOCK_REQ ((OMNET_MESSAGE_TYPE) 0x15)
|
||
#define OMNET_LOCK_GRANT ((OMNET_MESSAGE_TYPE) 0x16)
|
||
#define OMNET_LOCK_DENY ((OMNET_MESSAGE_TYPE) 0x17)
|
||
#define OMNET_UNLOCK ((OMNET_MESSAGE_TYPE) 0x18)
|
||
#define OMNET_LOCK_NOTIFY ((OMNET_MESSAGE_TYPE) 0x19)
|
||
|
||
#define OMNET_WSGROUP_SEND_REQ ((OMNET_MESSAGE_TYPE) 0x1E)
|
||
#define OMNET_WSGROUP_SEND_MIDWAY ((OMNET_MESSAGE_TYPE) 0x1F)
|
||
#define OMNET_WSGROUP_SEND_COMPLETE ((OMNET_MESSAGE_TYPE) 0x20)
|
||
#define OMNET_WSGROUP_SEND_DENY ((OMNET_MESSAGE_TYPE) 0x21)
|
||
|
||
#define OMNET_WORKSET_CLEAR ((OMNET_MESSAGE_TYPE) 0x28)
|
||
#define OMNET_WORKSET_NEW ((OMNET_MESSAGE_TYPE) 0x29)
|
||
#define OMNET_WORKSET_CATCHUP ((OMNET_MESSAGE_TYPE) 0x30)
|
||
|
||
#define OMNET_OBJECT_ADD ((OMNET_MESSAGE_TYPE) 0x32)
|
||
#define OMNET_OBJECT_CATCHUP ((OMNET_MESSAGE_TYPE) 0x33)
|
||
#define OMNET_OBJECT_REPLACE ((OMNET_MESSAGE_TYPE) 0x34)
|
||
#define OMNET_OBJECT_UPDATE ((OMNET_MESSAGE_TYPE) 0x35)
|
||
#define OMNET_OBJECT_DELETE ((OMNET_MESSAGE_TYPE) 0x36)
|
||
#define OMNET_OBJECT_MOVE ((OMNET_MESSAGE_TYPE) 0x37)
|
||
|
||
#define OMNET_MORE_DATA ((OMNET_MESSAGE_TYPE) 0x46)
|
||
|
||
|
||
//
|
||
//
|
||
// GENERIC OPERATION PACKET
|
||
//
|
||
// ObMan uses this structure for the following messages:
|
||
//
|
||
// OMNET_MORE_DATA uses first 1 field (4 bytes), plus data
|
||
//
|
||
// OMNET_WORKSET_NEW } use first 7 fields (24 bytes)
|
||
// OMNET_WORKSET_CATCHUP }
|
||
//
|
||
// OMNET_WORKSET_CLEAR uses first 6 fields (16 bytes);
|
||
// doesn't use <position), <flags>
|
||
//
|
||
// OMNET_OBJECT_MOVE uses first 7 fields (24 bytes);
|
||
// doesn't use <flags>
|
||
//
|
||
// OMNET_OBJECT_DELETE uses first 7 fields (24 bytes);
|
||
// doesn't use <position), <flags>
|
||
//
|
||
// OMNET_OBJECT_REPLACE } use first 8 fields (28 bytes), plus
|
||
// OMNET_OBEJCT_UPDATE } data; don't use <position), <flags>
|
||
//
|
||
// OMNET_OBJECT_ADD uses first 9 fields (32 bytes), plus
|
||
// data; doesn't use <flags>
|
||
//
|
||
// OMNET_OBJECT_CATCHUP uses all 12 fields (56 bytes), plus
|
||
// data
|
||
//
|
||
//
|
||
|
||
typedef struct tagOMNET_OPERATION_PKT
|
||
{
|
||
OMNET_PKT_HEADER header;
|
||
|
||
OM_WSGROUP_ID wsGroupID;
|
||
OM_WORKSET_ID worksetID;
|
||
BYTE position; // <position> for Add/Move/Catchup
|
||
BYTE flags; // <flags> for ObjectCatchUp
|
||
|
||
//
|
||
// Note: for WORKSET_NEW/CATCHUP messages, the two bytes occupied by
|
||
// the <position> and <flags> fields hold a NET_PRIORITY value.
|
||
//
|
||
|
||
OM_SEQUENCE_STAMP seqStamp; // operation sequence stamp
|
||
// (== addStamp for ObjectCatchUp,
|
||
// curr stamp for WorksetCatchUp)
|
||
OM_OBJECT_ID objectID;
|
||
|
||
//
|
||
// Note: for WORKSET_NEW/CATCHUP messages, the first byte occupied
|
||
// by the <objectID> field holds a BOOL indicating whether the
|
||
// workset is persistent.
|
||
//
|
||
|
||
TSHR_UINT32 totalSize; // total size of transfer
|
||
TSHR_UINT32 updateSize;
|
||
|
||
OM_SEQUENCE_STAMP positionStamp;
|
||
OM_SEQUENCE_STAMP replaceStamp;
|
||
OM_SEQUENCE_STAMP updateStamp;
|
||
}
|
||
OMNET_OPERATION_PKT;
|
||
typedef OMNET_OPERATION_PKT * POMNET_OPERATION_PKT;
|
||
|
||
#define OMNET_MORE_DATA_SIZE 4
|
||
#define OMNET_WORKSET_NEW_SIZE 24
|
||
#define OMNET_WORKSET_CATCHUP_SIZE 24
|
||
#define OMNET_WORKSET_CLEAR_SIZE 16
|
||
#define OMNET_OBJECT_MOVE_SIZE 24
|
||
#define OMNET_OBJECT_DELETE_SIZE 24
|
||
#define OMNET_OBJECT_REPLACE_SIZE 28
|
||
#define OMNET_OBJECT_UPDATE_SIZE 28
|
||
#define OMNET_OBJECT_ADD_SIZE 32
|
||
#define OMNET_OBJECT_CATCHUP_SIZE 56
|
||
|
||
//
|
||
// These define the sizes of the packets we used in R1.1: we must only send
|
||
// packets of this size to R1.1 systems.
|
||
//
|
||
|
||
//
|
||
//
|
||
// HELLO/WELCOME MESSAGE
|
||
//
|
||
// When ObMan attaches to a Domain that contains an outgoing call, it
|
||
// broadcasts an OMNET_WELCOME message on the well-known ObManControl
|
||
// channel.
|
||
//
|
||
// When ObMan attaches to a Domain that contains an incoming call, it
|
||
// broadcasts an OMNET_HELLO message on the well-known ObManControl
|
||
// channel.
|
||
//
|
||
// When ObMan receives a HELLO message, it replies with a WELCOME message,
|
||
// just as if it had just joined the call.
|
||
//
|
||
// This allows each late-joining ObMan in the call to discover the user ID
|
||
// of each of the other instances of ObMan.
|
||
//
|
||
// A late-joining ObMan uses this information by asking one of the nodes
|
||
// which WELCOMEd it for a copy of the ObManControl workset group.
|
||
//
|
||
// HELLO/WELCOME packets are NEVER compressed.
|
||
//
|
||
// WELCOME and HELLO messages have the following format:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOMNET_JOINER_PKT
|
||
{
|
||
OMNET_PKT_HEADER header;
|
||
TSHR_UINT32 capsLen; // == 4 in this version.
|
||
TSHR_UINT32 compressionCaps; // bitwise OR of OM_CAPS_ bits
|
||
}
|
||
OMNET_JOINER_PKT;
|
||
typedef OMNET_JOINER_PKT * POMNET_JOINER_PKT;
|
||
|
||
|
||
//
|
||
// The actual compression type used in any given packet is specified as the
|
||
// first byte of the packet (before the header and other structures
|
||
// specified in this file). The compression type is the numeric value of
|
||
// the bit position corresponding to the compression capability. For
|
||
// example, if XYZ compression has a capability value of 0x8, then packets
|
||
// compressed with XYZ will have 3 in their first byte.
|
||
//
|
||
// '0' is never valid as an OM_PROT_... compression type (which is why bit
|
||
// 1 is not used as an OM_CAPS_... flag).
|
||
//
|
||
#define OM_PROT_PKW_COMPRESSED 0x01
|
||
#define OM_PROT_NOT_COMPRESSED 0x02
|
||
|
||
//
|
||
// Values for compressionCaps. These must be separate bits, since they may
|
||
// be ORed together if a node supports multiple compression types.
|
||
//
|
||
// Note that OM_CAPS_NO_COMPRESSION is always supported.
|
||
//
|
||
// Bit 1 is not used.
|
||
//
|
||
#define OM_CAPS_PKW_COMPRESSION 0x0002
|
||
#define OM_CAPS_NO_COMPRESSION 0x0004
|
||
|
||
|
||
//
|
||
//
|
||
// LATE-JOINER PROTOCOL - WORKSET GROUP SEND REQUEST/SEND COMPLETE
|
||
//
|
||
// The SEND_REQUEST message is sent when ObMan has "late-joined" a
|
||
// particular workset group and would like another node to send it the
|
||
// current contents.
|
||
//
|
||
// The message is sent to an arbitrary "helper" node (known to have a copy
|
||
// of the workset group) on its single-user channel.
|
||
//
|
||
// The recipient responds by flushing the relevant channel (in R1.1, a
|
||
// no-op; in R2.0, perform a WORKSET_CHECKPOINT) and then sending the
|
||
// contents of the workset.
|
||
//
|
||
// When the WORKSET_CATCHUP messages have been sent, we send a
|
||
// WSGROUP_SEND_MIDWAY message to let the late joiner know that it now
|
||
// knows about all the worksets which are currently in use (otherwise, it
|
||
// might create a workset already in use which happened to be locked on the
|
||
// sending machine add then an object to it.
|
||
//
|
||
// The SEND_MIDWAY message also containing the max sequence number
|
||
// previously used by the late joiner's ID in this workset group (to
|
||
// prevent re-use of object IDs).
|
||
//
|
||
// When the contents have been sent, i.e. after the last data packet of
|
||
// the last object in the last workset of the group, the helper sends a
|
||
// SEND_COMPLETE message.
|
||
//
|
||
// If the chosen helper node is not in a position to send the contents of
|
||
// the workset group, it must repsond with a SEND_DENY message, upon
|
||
// receipt of which the late joiner will choose someone else to catch up
|
||
// from.
|
||
//
|
||
// The SEND_REQUEST, SEND_MIDWAY, SEND_COMPLETE and SEND_DENY message
|
||
// packets have the following structure:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOMNET_WSGROUP_SEND_PKT
|
||
{
|
||
OMNET_PKT_HEADER header;
|
||
OM_WSGROUP_ID wsGroupID;
|
||
BYTE pad1;
|
||
TSHR_UINT16 correlator; // Holds the catchup correlator
|
||
OM_OBJECT_ID objectID;
|
||
TSHR_UINT32 maxObjIDSeqUsed;
|
||
}
|
||
OMNET_WSGROUP_SEND_PKT;
|
||
typedef OMNET_WSGROUP_SEND_PKT * POMNET_WSGROUP_SEND_PKT;
|
||
|
||
|
||
//
|
||
//
|
||
// LOCKING PROTOCOL - LOCK PACKET
|
||
//
|
||
// When ObMan wants to lock a workset/object, it broadcasts one of these
|
||
// packets (with type == OMNET_LOCK_REQ).
|
||
//
|
||
// When ObMan receives one of these packets, it decides to deny or grant
|
||
// the lock to the sender, and replies with another packet of the same
|
||
// structure but with type == OMNET_LOCK_DENY or OMNET_LOCK_GRANT as
|
||
// appropriate.
|
||
//
|
||
// When ObMan wants to unlock a workste/object it has previously locked, it
|
||
// broadcasts one of these packets with type == OMNET_UNLOCK.
|
||
//
|
||
|
||
typedef struct tagOMNET_LOCK_PKT
|
||
{
|
||
OMNET_PKT_HEADER header;
|
||
OM_WSGROUP_ID wsGroupID;
|
||
OM_WORKSET_ID worksetID;
|
||
TSHR_UINT16 data1; // used as correlator for GRANT/DENY
|
||
// used to indicate who's got lock
|
||
// for NOTIFY
|
||
// lon: need to keep pLockReqCB field for backward compatability!
|
||
void * pLockReqCB; // R1.1 uses this to find the lock
|
||
// request CB
|
||
}
|
||
OMNET_LOCK_PKT;
|
||
typedef OMNET_LOCK_PKT * POMNET_LOCK_PKT;
|
||
|
||
|
||
//
|
||
//
|
||
// DATA STRUCTURES
|
||
//
|
||
//
|
||
|
||
|
||
//
|
||
//
|
||
// OPERATION TYPES
|
||
//
|
||
// This is the type defined for operations which Clients may perform on
|
||
// objects and worksets. Pending operation lists use this type.
|
||
//
|
||
//
|
||
|
||
typedef TSHR_UINT16 OM_OPERATION_TYPE;
|
||
|
||
//
|
||
// Possible values for a OM_OPERATION_TYPE variable:
|
||
//
|
||
|
||
#define NULL_OP ((OM_OPERATION_TYPE) 0)
|
||
#define WORKSET_CLEAR ((OM_OPERATION_TYPE) 1)
|
||
#define OBJECT_ADD ((OM_OPERATION_TYPE) 2)
|
||
#define OBJECT_MOVE ((OM_OPERATION_TYPE) 3)
|
||
#define OBJECT_DELETE ((OM_OPERATION_TYPE) 4)
|
||
#define OBJECT_REPLACE ((OM_OPERATION_TYPE) 5)
|
||
#define OBJECT_UPDATE ((OM_OPERATION_TYPE) 6)
|
||
|
||
|
||
//
|
||
//
|
||
// PENDING OPERATION LISTS
|
||
//
|
||
// When ObMan receives a request (either from a local Client or over the
|
||
// network) to delete, update or replace an object, or to clear a workset,
|
||
// it cannot perform the operation until the local Client has confirmed it.
|
||
// These operations are therefore put in a list and processed when the
|
||
// appropriate Confirm function is invoked.
|
||
//
|
||
// This list is hung off the workset record; its elements have the
|
||
// following format:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_PENDING_OP
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
POM_OBJECT pObj; // NULL if a clear operation
|
||
POM_OBJECTDATA pData;
|
||
|
||
OM_SEQUENCE_STAMP seqStamp; // the sequence stamp which was
|
||
// current in the workset when the
|
||
// operation was invoked
|
||
|
||
OM_OPERATION_TYPE type; // == WORKSET_CLEAR, OBJECT_DELETE,
|
||
// OBJECT_UPDATE or OBJECT_REPLACE
|
||
|
||
WORD pad1;
|
||
|
||
}
|
||
OM_PENDING_OP;
|
||
typedef OM_PENDING_OP * POM_PENDING_OP;
|
||
|
||
|
||
//
|
||
//
|
||
// OBJECT RECORDS
|
||
//
|
||
// This structure holds information about a particular object,
|
||
//
|
||
typedef struct tagOM_OBJECT
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
OM_OBJECT_ID objectID; // Unique within domain
|
||
POM_OBJECTDATA pData; // Ptr to data
|
||
|
||
OM_SEQUENCE_STAMP addStamp; // the sequence stamps used
|
||
OM_SEQUENCE_STAMP positionStamp; OM_SEQUENCE_STAMP replaceStamp;
|
||
OM_SEQUENCE_STAMP updateStamp;
|
||
|
||
UINT updateSize; // size of (all) updates
|
||
|
||
BYTE flags; // defined below
|
||
OM_POSITION position; // either LAST or FIRST,
|
||
// indicating where the object
|
||
// was most recently placed
|
||
WORD pad1;
|
||
}
|
||
OM_OBJECT;
|
||
|
||
|
||
BOOL __inline ValidObject(POM_OBJECT pObj)
|
||
{
|
||
return(!IsBadWritePtr(pObj, sizeof(OM_OBJECT)));
|
||
}
|
||
void __inline ValidateObject(POM_OBJECT pObj)
|
||
{
|
||
ASSERT(ValidObject(pObj));
|
||
}
|
||
|
||
|
||
//
|
||
// Flags used:
|
||
//
|
||
|
||
#define DELETED 0x0001
|
||
#define PENDING_DELETE 0x0002
|
||
|
||
|
||
//
|
||
//
|
||
// UNUSED OBJECTS LISTS
|
||
//
|
||
// When a Client allocates an object using OM_ObjectAlloc, a reference to
|
||
// the memory allocated is stored in the Client's unused objects list for
|
||
// this workset group.
|
||
//
|
||
// The reference is removed when the Client either
|
||
//
|
||
// - discards the object using OM_ObjectDiscard, or
|
||
//
|
||
// - inserts the object in a workset with an Add, Update or Replace
|
||
// function.
|
||
//
|
||
// This list of objects (which is hung off the usage record) is checked
|
||
// when a workset is closed to discard any objects the Client didn't
|
||
// explicitly discard or use.
|
||
//
|
||
// The elements of the list have the following form:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_OBJECTDATA_LIST
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
POM_OBJECTDATA pData;
|
||
|
||
UINT size; // Used to verify that Client hasn't grown size
|
||
|
||
OM_WORKSET_ID worksetID;
|
||
BYTE pad1;
|
||
WORD pad2;
|
||
}
|
||
OM_OBJECTDATA_LIST;
|
||
typedef OM_OBJECTDATA_LIST * POM_OBJECTDATA_LIST;
|
||
|
||
|
||
//
|
||
//
|
||
// OBJECTS-IN-USE LISTS
|
||
//
|
||
// When a Client reads an object using OM_ObjectRead, the use count of the
|
||
// chunk of memory containing the object is increased.
|
||
//
|
||
// The use count is deceremented again when the Client calls
|
||
// OM_ObjectRelease, but if the Client abends, or simply closes a workset
|
||
// without releasing the objects it has read, we still need to be able to
|
||
// free the memory.
|
||
//
|
||
// Therefore we keep a list, on a per-workset-group basis, of the objects
|
||
// that a Client is using. Objects (identified by handles) are added to
|
||
// the list when a Client calls OM_ObjectRead, and removed from the list
|
||
// when the Client calls OM_ObjectRelease.
|
||
//
|
||
// In addition, the list is checked when a workset is closed to release any
|
||
// handles the Client didn't release explicitly.
|
||
//
|
||
// Like the unused objects list, this list is hung off the usage record.
|
||
//
|
||
// The elements of these lists have the following form:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_OBJECT_LIST
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
POM_OBJECT pObj;
|
||
|
||
OM_WORKSET_ID worksetID; // the ID of the workset
|
||
BYTE pad1;
|
||
WORD pad2;
|
||
}
|
||
OM_OBJECT_LIST;
|
||
typedef OM_OBJECT_LIST * POM_OBJECT_LIST;
|
||
|
||
|
||
//
|
||
//
|
||
// NODE LIST STRUCTURES
|
||
//
|
||
// When requesting locks etc. from other nodes in a Domain, ObMan keeps a
|
||
// list of remote nodes which it expects a reply from. A node is
|
||
// identified by the MCS user ID of the instance of ObMan running on that
|
||
// node.
|
||
//
|
||
// The elements of these lists have the folllowing form:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_NODE_LIST
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
NET_UID userID; // user ID of remote ObMan
|
||
|
||
WORD pad1;
|
||
}
|
||
OM_NODE_LIST;
|
||
|
||
typedef OM_NODE_LIST * POM_NODE_LIST;
|
||
|
||
|
||
//
|
||
//
|
||
// LOCK REQUEST CONTROL BLOCKS
|
||
//
|
||
// When ObMan is in the process of getting a lock for a workset or object
|
||
// it creates one of these structures to correlate the lock replies.
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_LOCK_REQ
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
PUT_CLIENT putTask; // task to notify on success
|
||
// or failure
|
||
OM_CORRELATOR correlator; // returned by WorksetLockReq
|
||
OM_WSGROUP_ID wsGroupID; // workset group and workset
|
||
OM_WORKSET_ID worksetID; // containing the lock
|
||
|
||
POM_WSGROUP pWSGroup;
|
||
|
||
BASEDLIST nodes; // MCS user IDs of nodes which
|
||
// haven't yet replies to req
|
||
// (an OM_NODE_LIST list)
|
||
|
||
WORD retriesToGo; // Decremented on each timeout
|
||
OM_WSGROUP_HANDLE hWSGroup;
|
||
BYTE type; // PRIMARY or SECONDARY
|
||
}
|
||
OM_LOCK_REQ;
|
||
typedef OM_LOCK_REQ * POM_LOCK_REQ;
|
||
|
||
#define LOCK_PRIMARY 0x01
|
||
#define LOCK_SECONDARY 0x02
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// CLIENT LIST STRUCTURE
|
||
//
|
||
// The lists of Clients stored per workset group and per workset contain
|
||
// elements of this type. The <hWSGroup> field refers to the workset group
|
||
// handle by which the Client knows the workset group concerned.
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_CLIENT_LIST
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
PUT_CLIENT putTask; // the Client's putTask
|
||
WORD mode;
|
||
OM_WSGROUP_HANDLE hWSGroup;
|
||
BYTE pad1;
|
||
}
|
||
OM_CLIENT_LIST;
|
||
typedef OM_CLIENT_LIST * POM_CLIENT_LIST;
|
||
|
||
|
||
//
|
||
//
|
||
// WORKSET RECORDS
|
||
//
|
||
// This structure holds the state information for a workset. It resides at
|
||
// offset zero (0) in the huge memory block associated with this workset.
|
||
//
|
||
// ObMan allocates a workset record when a workset is created and discards
|
||
// it when the workset is discarded.
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_WORKSET
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
UINT numObjects; // the current number of objects in
|
||
// workset (excluding the sentinels)
|
||
|
||
UINT genNumber; // current workset generation number
|
||
|
||
OM_SEQUENCE_STAMP clearStamp; // the clear stamp for the workset
|
||
|
||
NET_PRIORITY priority; // MCS priority for the workset
|
||
OM_WORKSET_ID worksetID;
|
||
BYTE lockState; // one of the values defined below
|
||
|
||
WORD lockCount; // LOCAL lock count
|
||
NET_UID lockedBy; // MCS user ID of node which has the
|
||
// lock, if any
|
||
|
||
BASEDLIST objects; // root of list of workset's objects
|
||
|
||
UINT bytesUnacked; // bytes still to be acked
|
||
|
||
BASEDLIST pendingOps; // root of list of operations which
|
||
// are pending for this workset
|
||
|
||
BASEDLIST clients; // root of list of Clients which
|
||
// have this workset open
|
||
BOOL fTemp;
|
||
}
|
||
OM_WORKSET;
|
||
typedef OM_WORKSET * POM_WORKSET;
|
||
|
||
void __inline ValidateWorkset(POM_WORKSET pWorkset)
|
||
{
|
||
ASSERT(!IsBadWritePtr(pWorkset, sizeof(OM_WORKSET)));
|
||
}
|
||
|
||
//
|
||
// Possible values for the <lockState> field above:
|
||
//
|
||
|
||
#define UNLOCKED 0x00
|
||
#define LOCKING 0x01
|
||
#define LOCKED 0x02
|
||
#define LOCK_GRANTED 0x03
|
||
|
||
|
||
//
|
||
//
|
||
// WORKSET GROUP RECORDS
|
||
//
|
||
// This structure holds information about a workset group.
|
||
//
|
||
// ObMan maintains one of these structures for each workset group with
|
||
// which one or more local Clients are registered.
|
||
//
|
||
// It will be discarded when the last local Client registered with the
|
||
// workset group deregisters from it.
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_WSGROUP
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
OMWSG wsg;
|
||
OMFP fpHandler;
|
||
|
||
NET_CHANNEL_ID channelID; // MCS channel ID used for WSG
|
||
OM_WSGROUP_ID wsGroupID; // workset group ID
|
||
BYTE state; // one of the values defined below
|
||
|
||
POM_OBJECT pObjReg; // Registration object in the OMC workset
|
||
|
||
BASEDLIST clients; // the Clients using the WSG
|
||
|
||
POM_DOMAIN pDomain;
|
||
|
||
NET_UID helperNode; // ID of the node we are catching up from.
|
||
WORD valid:1;
|
||
WORD toBeDiscarded:1;
|
||
|
||
UINT bytesUnacked; // sum of bytesUnacked field for each
|
||
// workset in the workset group
|
||
|
||
BYTE sendMidwCount; // # of SEND_MIDWAYs received
|
||
BYTE sendCompCount; // # of SEND_MIDWAYs received
|
||
OM_CORRELATOR catchupCorrelator; // Used to correlate SEND_REQUESTS
|
||
// to SEND_MIDWAYs and
|
||
// SEND_COMPLETEs.
|
||
POM_WORKSET apWorksets[ OM_MAX_WORKSETS_PER_WSGROUP + 1];
|
||
}
|
||
OM_WSGROUP;
|
||
|
||
|
||
|
||
void __inline ValidateWSGroup(POM_WSGROUP pWSGroup)
|
||
{
|
||
ASSERT(!IsBadWritePtr(pWSGroup, sizeof(OM_WSGROUP)));
|
||
}
|
||
|
||
|
||
|
||
//
|
||
// Workset group <state> values
|
||
//
|
||
|
||
#define INITIAL 0x00
|
||
#define LOCKING_OMC 0x01
|
||
#define PENDING_JOIN 0x02
|
||
#define PENDING_SEND_MIDWAY 0x03
|
||
#define PENDING_SEND_COMPLETE 0x04
|
||
#define WSGROUP_READY 0x05
|
||
|
||
|
||
//
|
||
//
|
||
// USAGE RECORDS
|
||
//
|
||
// A usage record identifies a Client's use of a particular workset group
|
||
// and holds state information about that usage.
|
||
//
|
||
// Usage records reside in the OMGLBOAL memory block at the offset (from
|
||
// the base) specified in the Client record.
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_USAGE_REC
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
POM_WSGROUP pWSGroup; // Client pointer to workset group
|
||
|
||
BASEDLIST unusedObjects; // start sentinel in list of
|
||
// pointers to unused objects
|
||
|
||
BASEDLIST objectsInUse; // OM_OBJECT_LIST
|
||
|
||
BYTE mode;
|
||
BYTE flags;
|
||
|
||
BYTE worksetOpenFlags[(OM_MAX_WORKSETS_PER_WSGROUP + 7)/8];
|
||
|
||
// bitfield array of flags
|
||
// indicating the worksets the
|
||
// Client has open
|
||
}
|
||
OM_USAGE_REC;
|
||
typedef OM_USAGE_REC * POM_USAGE_REC;
|
||
|
||
__inline void ValidateUsageRec(POM_USAGE_REC pUsageRec)
|
||
{
|
||
ASSERT(!IsBadWritePtr(pUsageRec, sizeof(OM_USAGE_REC)));
|
||
}
|
||
|
||
//
|
||
// Values for flags:
|
||
//
|
||
|
||
#define ADDED_TO_WSGROUP_LIST 0x0002
|
||
#define PWSGROUP_IS_PREGCB 0x0004
|
||
|
||
//
|
||
//
|
||
// LOCK STACKS
|
||
//
|
||
// Clients must request and release object and workset locks in accordance
|
||
// with the Universal Locking Order as defined in the Functional Spec (in
|
||
// order to avoid deadlock).
|
||
//
|
||
// In order to detect lock order violations, ObMan maintains, for each
|
||
// Client, a stack of locks which the Client holds or has requested. This
|
||
// stack is implemented as a linked list, with the most recently acquired
|
||
// lock (which must, by definition, be the one latest in the Universal
|
||
// Locking Order) being the first element.
|
||
//
|
||
// A Client's lock stack is initialised when the Client registers with
|
||
// ObMan and discarded when the Client deregisters from ObMan. Lock stacks
|
||
// are hung off the Client record.
|
||
//
|
||
// Note that we need the store the object ID here, as opposed to the
|
||
// handle, since we must enforce the universal lock order across all nodes.
|
||
//
|
||
// Elements of lock stacks have the following form:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_LOCK
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
POM_WSGROUP pWSGroup; // Client pointer to workset group
|
||
// needed to detect lock violations
|
||
|
||
OM_OBJECT_ID objectID; // the object ID is 0 if this is a
|
||
// workset lock (in R1.1, always).
|
||
OM_WORKSET_ID worksetID;
|
||
BYTE pad1;
|
||
WORD pad2;
|
||
}
|
||
OM_LOCK;
|
||
typedef OM_LOCK * POM_LOCK;
|
||
|
||
|
||
int __inline CompareLocks(POM_LOCK pLockFirst, POM_LOCK pLockSecond)
|
||
{
|
||
int result;
|
||
|
||
result = (pLockSecond->pWSGroup->wsg - pLockFirst->pWSGroup->wsg);
|
||
|
||
if (result == 0)
|
||
{
|
||
// Same WSG, so compare worksets
|
||
result = (pLockSecond->worksetID - pLockFirst->worksetID);
|
||
}
|
||
|
||
return(result);
|
||
}
|
||
|
||
|
||
//
|
||
//
|
||
// CLIENT RECORD
|
||
//
|
||
// ObMan maintains instance data for every registered Client. This
|
||
// structure, a Client record, holds the Client instance data.
|
||
//
|
||
// A Client's ObMan handle is a Client pointer to this structure.
|
||
//
|
||
// A Client's workset group handle is an index into the array of usage record
|
||
// ptrs.
|
||
//
|
||
// If the value of apUsageRecs is 0 or -1, x is not a valid workset
|
||
// group handle.
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_CLIENT
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
PUT_CLIENT putTask;
|
||
|
||
BOOL exitProcReg:1;
|
||
BOOL hiddenHandlerReg:1;
|
||
|
||
BASEDLIST locks; // root of list of locks held
|
||
|
||
POM_USAGE_REC apUsageRecs[OMWSG_MAXPERCLIENT];
|
||
BOOL wsgValid[OMWSG_MAXPERCLIENT];
|
||
}
|
||
OM_CLIENT;
|
||
|
||
|
||
|
||
BOOL __inline ValidWSGroupHandle(POM_CLIENT pomClient, OM_WSGROUP_HANDLE hWSGroup)
|
||
{
|
||
return((hWSGroup != 0) &&
|
||
(pomClient->wsgValid[hWSGroup]) &&
|
||
(pomClient->apUsageRecs[hWSGroup] != NULL));
|
||
}
|
||
|
||
|
||
//
|
||
//
|
||
// DOMAIN RECORD
|
||
//
|
||
// This structure holds information about a Domain. We support two:
|
||
// * The current call
|
||
// * Limbo (no call) for cleanup after a call and maintenance of info
|
||
// across calls
|
||
//
|
||
typedef struct tagOM_DOMAIN
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
UINT callID; // MCS Domain Handle
|
||
|
||
NET_UID userID; // ObMan's MCS user ID and token ID
|
||
NET_TOKEN_ID tokenID; // for this domain
|
||
|
||
NET_CHANNEL_ID omcChannel; // ObMan's broadcast channel
|
||
BYTE state; // one of the values defined below
|
||
BYTE omchWSGroup; // ObMan's hWSGroup for this domain's
|
||
|
||
BOOL valid:1;
|
||
BOOL sendEventOutstanding:1;
|
||
|
||
UINT compressionCaps; // Domain-wide compression caps
|
||
|
||
BASEDLIST wsGroups; // root of list of workset groups
|
||
BASEDLIST pendingRegs; // root of list of pending workset
|
||
// group registration request
|
||
BASEDLIST pendingLocks; // root of list of pending
|
||
// lock requests
|
||
BASEDLIST receiveList; // root of list of control blocks
|
||
// for receives in progress
|
||
BASEDLIST bounceList; // root of list of control blocks
|
||
// for bounced messages
|
||
BASEDLIST helperCBs; // root of list of helper CBs for
|
||
// checkpoints in progress
|
||
|
||
BASEDLIST sendQueue[NET_NUM_PRIORITIES];
|
||
// array of roots of list of send
|
||
// queue instructions (by priority)
|
||
BOOL sendInProgress[NET_NUM_PRIORITIES];
|
||
// array of send-in-progress flags
|
||
}
|
||
OM_DOMAIN;
|
||
|
||
|
||
//
|
||
// Possible values for <state> field:
|
||
//
|
||
|
||
#define PENDING_ATTACH 0x01
|
||
#define PENDING_JOIN_OWN 0x02
|
||
#define PENDING_JOIN_OMC 0x03
|
||
#define PENDING_TOKEN_ASSIGN 0x04
|
||
#define PENDING_TOKEN_GRAB 0x05
|
||
#define PENDING_TOKEN_INHIBIT 0x06
|
||
#define PENDING_WELCOME 0x07
|
||
#define GETTING_OMC 0x08
|
||
#define DOMAIN_READY 0x09
|
||
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// SHARED MEMORY STRUCTURE
|
||
//
|
||
// This structure holds various private (to ObMan) state information.
|
||
//
|
||
// The ObMan task allocates and initialises one instance of this structure
|
||
// when it initialises; it resides at the base of the OMGLOBAL memory
|
||
// block.
|
||
//
|
||
// It is discarded when the ObMan task terminates.
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_PRIMARY
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
PUT_CLIENT putTask;
|
||
PMG_CLIENT pmgClient; // OM's network layer handle
|
||
PCM_CLIENT pcmClient; // OM's Call Manager handle
|
||
|
||
BASEDLIST domains; // Domains
|
||
OM_CLIENT clients[OMCLI_MAX]; // Secondaries
|
||
|
||
UINT objectIDsequence;
|
||
|
||
BOOL exitProcReg:1;
|
||
BOOL eventProcReg:1;
|
||
|
||
OM_CORRELATOR correlator;
|
||
WORD pad1;
|
||
|
||
LPBYTE pgdcWorkBuf;
|
||
BYTE compressBuffer[OM_NET_SEND_POOL_SIZE / 2];
|
||
}
|
||
OM_PRIMARY;
|
||
|
||
|
||
void __inline ValidateOMP(POM_PRIMARY pomPrimary)
|
||
{
|
||
ASSERT(!IsBadWritePtr(pomPrimary, sizeof(OM_PRIMARY)));
|
||
}
|
||
|
||
|
||
void __inline ValidateOMS(POM_CLIENT pomClient)
|
||
{
|
||
extern POM_PRIMARY g_pomPrimary;
|
||
|
||
ValidateOMP(g_pomPrimary);
|
||
|
||
ASSERT(!IsBadWritePtr(pomClient, sizeof(OM_CLIENT)));
|
||
|
||
ASSERT(pomClient < &(g_pomPrimary->clients[OMCLI_MAX]));
|
||
ASSERT(pomClient >= &(g_pomPrimary->clients[OMCLI_FIRST]));
|
||
}
|
||
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// Workset group registration/move request control block
|
||
//
|
||
// This structure is used to pass the parameters of a workset group
|
||
// registration/move request to the ObMan task (from a Client task).
|
||
//
|
||
// Not all fields are used by both the registration and the move process.
|
||
//
|
||
// The <type> field is used to distinguish between a WSGroupMove and a
|
||
// WSGroupRegister.
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_WSGROUP_REG_CB
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
PUT_CLIENT putTask;
|
||
UINT callID;
|
||
|
||
OMWSG wsg;
|
||
OMFP fpHandler;
|
||
|
||
OM_CORRELATOR correlator;
|
||
OM_CORRELATOR lockCorrelator;
|
||
OM_CORRELATOR channelCorrelator;
|
||
WORD retryCount;
|
||
|
||
POM_USAGE_REC pUsageRec;
|
||
POM_WSGROUP pWSGroup;
|
||
|
||
POM_DOMAIN pDomain; // ObMan pointer to Domain record
|
||
BOOL valid;
|
||
|
||
OM_WSGROUP_HANDLE hWSGroup;
|
||
BYTE type; // REGISTER or MOVE
|
||
BYTE mode; // PRIMARY or SECONDARY
|
||
BYTE flags; // see below
|
||
}
|
||
OM_WSGROUP_REG_CB;
|
||
typedef OM_WSGROUP_REG_CB * POM_WSGROUP_REG_CB;
|
||
|
||
//
|
||
// Values for the <type> field:
|
||
//
|
||
|
||
#define WSGROUP_MOVE 0x01
|
||
#define WSGROUP_REGISTER 0x02
|
||
|
||
//
|
||
// Flags for the <flags> field:
|
||
//
|
||
|
||
#define BUMPED_CBS 0x0001 // indicates whether we bumped use
|
||
// counts of pWSGroup, pDomain
|
||
#define LOCKED_OMC 0x0002 // indicates whether we've locked
|
||
// ObManControl
|
||
|
||
//
|
||
// Values for the <mode> field (we use the flag macro because the values
|
||
// may be ORed together and so need to be bit-independent):
|
||
//
|
||
|
||
#define PRIMARY 0x0001
|
||
#define SECONDARY 0x0002
|
||
|
||
|
||
//
|
||
//
|
||
// HELPER CONTROL BLOCK
|
||
//
|
||
// When we receive a WSG_SEND_REQUEST from a remote node, we checkpoint the
|
||
// workset group requested. This is an asynchronous process (it's
|
||
// essentially getting a lock on a dummy workset), so we need to store the
|
||
// details of the remote node away somewhere. We do this using a help CB
|
||
// with the following structure:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_HELPER_CB
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
NET_UID lateJoiner; // MCS user ID of late joiner
|
||
OM_CORRELATOR remoteCorrelator;
|
||
|
||
POM_WSGROUP pWSGroup; // pWSGroup is bumped during
|
||
// checkpoint
|
||
|
||
OM_CORRELATOR lockCorrelator; // returned by WorksetLockReq
|
||
// and recd in WORKSET_LOCK_CON
|
||
|
||
WORD pad1;
|
||
}
|
||
OM_HELPER_CB;
|
||
typedef OM_HELPER_CB * POM_HELPER_CB;
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// THE SEND QUEUE
|
||
//
|
||
// For each Domain, and for each network priority, ObMan maintains a queue
|
||
// of message and data to be sent to the network. Clients, when executing
|
||
// API functions, cause instructions to be added to the tail of one of
|
||
// these queues.
|
||
//
|
||
// The ObMan task, in response to an OMINT_EVENT_SEND_QUEUE event, processes as
|
||
// many send queue operations as possible, giving up for a while when it
|
||
// runs out of network buffers.
|
||
//
|
||
// This is subject to the restriction that no operations are processed from
|
||
// one send queue when operations exist on a queue of higher priority in
|
||
// the same Domain.
|
||
//
|
||
// Instructions on the send queue have the following format:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_SEND_INST
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
UINT callID; // the relevant Domain
|
||
|
||
NET_CHANNEL_ID channel; // the channel to send the event on
|
||
NET_PRIORITY priority; // priority to send event on
|
||
|
||
POM_WSGROUP pWSGroup;
|
||
POM_WORKSET pWorkset;
|
||
POMNET_PKT_HEADER pMessage;
|
||
POM_OBJECT pObj;
|
||
|
||
POM_OBJECTDATA pDataStart;
|
||
POM_OBJECTDATA pDataNext;
|
||
|
||
WORD messageSize; // length of message at pMessage
|
||
OMNET_MESSAGE_TYPE messageType; // == OMNET_OBJECT_ADD, etc.
|
||
|
||
UINT dataLeftToGo; // number of bytes of data left to
|
||
// be sent
|
||
|
||
UINT compressOrNot; // Some packets are never compressed
|
||
|
||
}
|
||
OM_SEND_INST;
|
||
typedef OM_SEND_INST * POM_SEND_INST;
|
||
|
||
//
|
||
//
|
||
// RECEIVE LIST
|
||
//
|
||
// ObMan maintains a list of structures holding information about data
|
||
// transfers (receives) which have begun but not finished. This is known
|
||
// as the receive list.
|
||
//
|
||
// When ObMan receives a header packet for an Add, Update or Replace
|
||
// operation, it adds an entry to the receive list. Subsequent data
|
||
// packets are then correlated with this entry, until the entire object has
|
||
// been received, at which point the Add/Update/Replace operation is
|
||
// carried out.
|
||
//
|
||
// The receive list is a linked list of entries with the following format:
|
||
//
|
||
//
|
||
|
||
typedef struct tagOM_RECEIVE_CB
|
||
{
|
||
STRUCTURE_STAMP
|
||
|
||
BASEDLIST chain;
|
||
|
||
POM_DOMAIN pDomain; // Domain record pointer
|
||
|
||
POMNET_OPERATION_PKT pHeader; // ObMan pointer to message header
|
||
|
||
void * pData; // ObMan pointer to the data that
|
||
// is being transferred
|
||
|
||
UINT bytesRecd; // total bytes received so far for
|
||
// this transfer
|
||
|
||
LPBYTE pCurrentPosition; // points to where next chunk
|
||
// of data should be copied
|
||
|
||
NET_PRIORITY priority; // priority of data transfer
|
||
NET_CHANNEL_ID channel;
|
||
|
||
}
|
||
OM_RECEIVE_CB;
|
||
typedef OM_RECEIVE_CB * POM_RECEIVE_CB;
|
||
|
||
|
||
|
||
//
|
||
// HANDLE <--> PTR CONVERSION ROUTINES
|
||
// Object, usage, domain, workset group, worksets
|
||
//
|
||
|
||
|
||
POM_WSGROUP __inline GetOMCWsgroup(POM_DOMAIN pDomain)
|
||
{
|
||
POM_WSGROUP pWSGroup;
|
||
|
||
pWSGroup = (POM_WSGROUP)COM_BasedListFirst(&(pDomain->wsGroups),
|
||
FIELD_OFFSET(OM_WSGROUP, chain));
|
||
|
||
ValidateWSGroup(pWSGroup);
|
||
|
||
return(pWSGroup);
|
||
}
|
||
|
||
|
||
|
||
POM_WORKSET __inline GetOMCWorkset(POM_DOMAIN pDomain, OM_WORKSET_ID worksetID)
|
||
{
|
||
POM_WSGROUP pWSGroup;
|
||
|
||
pWSGroup = GetOMCWsgroup(pDomain);
|
||
return(pWSGroup->apWorksets[worksetID]);
|
||
}
|
||
|
||
|
||
|
||
|
||
OM_CORRELATOR __inline NextCorrelator(POM_PRIMARY pomPrimary)
|
||
{
|
||
return(pomPrimary->correlator++);
|
||
}
|
||
|
||
|
||
|
||
void __inline UpdateWorksetGeneration(POM_WORKSET pWorkset, POMNET_OPERATION_PKT pPacket)
|
||
{
|
||
pWorkset->genNumber = max(pWorkset->genNumber, pPacket->seqStamp.genNumber) + 1;
|
||
}
|
||
|
||
|
||
//
|
||
//
|
||
// CHECK_WORKSET_NOT_EXHAUSTED(pWorkset)
|
||
//
|
||
// This macro checks that the specified workset is not exhausted. If it
|
||
// is, it calls DC_QUIT.
|
||
//
|
||
//
|
||
|
||
#define CHECK_WORKSET_NOT_EXHAUSTED(pWorkset) \
|
||
\
|
||
if (pWorkset->genNumber == OM_MAX_GENERATION_NUMBER) \
|
||
{ \
|
||
WARNING_OUT(("Workset %hx exhausted", pWorkset->worksetID)); \
|
||
rc = OM_RC_WORKSET_EXHAUSTED; \
|
||
DC_QUIT; \
|
||
}
|
||
|
||
//
|
||
//
|
||
// CHECK_WORKSET_NOT_LOCKED(pWorkset)
|
||
//
|
||
// This macro checks that the specified workset is not locked. If it is,
|
||
// it calls DC_QUIT with an error.
|
||
//
|
||
//
|
||
|
||
#define CHECK_WORKSET_NOT_LOCKED(pWorkset) \
|
||
\
|
||
if (pWorkset->lockState == LOCK_GRANTED) \
|
||
{ \
|
||
rc = OM_RC_WORKSET_LOCKED; \
|
||
WARNING_OUT(("Workset %hx locked - can't proceed", worksetID)); \
|
||
DC_QUIT; \
|
||
}
|
||
|
||
|
||
//
|
||
//
|
||
// OBJECT ID MANIPULATION
|
||
//
|
||
// These macros manipulate object IDs.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OBJECT_ID_IS_NULL(objectID)
|
||
//
|
||
// This macro evaluates to TRUE if the supplied object ID is a null ID,
|
||
// and FALSE otherwise.
|
||
//
|
||
//
|
||
|
||
#define OBJECT_ID_IS_NULL(objectID) \
|
||
\
|
||
(((objectID).creator == 0) && ((objectID).sequence == 0))
|
||
|
||
//
|
||
//
|
||
// GET_NEXT_OBJECT_ID(objectID, pDomain, pWorkset)
|
||
//
|
||
// This macro allocates a new object ID for the workset specified by
|
||
// <pWorkset>. It copies the ID into the structure specified by
|
||
// <objectID>.
|
||
//
|
||
// The first field in the ID is ObMan's MCS user ID in the Domain to which
|
||
// the workset group <pWSGroup> belongs.
|
||
//
|
||
//
|
||
|
||
#define GET_NEXT_OBJECT_ID(objectID, pDomain, pomPrimary) \
|
||
(objectID).creator = pDomain->userID; \
|
||
(objectID).sequence = pomPrimary->objectIDsequence++; \
|
||
(objectID).pad1 = 0
|
||
|
||
//
|
||
//
|
||
// OBJECT_IDS_ARE_EQUAL(objectID1, objectID2)
|
||
//
|
||
// Evaluates to TRUE if the two object IDs are equal and FALSE otherwise.
|
||
//
|
||
//
|
||
|
||
#define OBJECT_IDS_ARE_EQUAL(objectID1, objectID2) \
|
||
\
|
||
(memcmp(&(objectID1), &(objectID2), sizeof(OM_OBJECT_ID)) == 0)
|
||
|
||
//
|
||
//
|
||
// SEQUENCE STAMP MANIPULATION
|
||
//
|
||
// These macro manipulate sequence stamps.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// GET_CURR_SEQ_STAMP(stamp, pWSGroup, pWorkset)
|
||
//
|
||
// This macro copies the current sequence stamp of the workset specified by
|
||
// <pWorkset> into the sequence stamp structure identified by <stamp>.
|
||
//
|
||
//
|
||
|
||
#define GET_CURR_SEQ_STAMP(stamp, pDomain, pWorkset) \
|
||
\
|
||
(stamp).userID = pDomain->userID; \
|
||
(stamp).genNumber = pWorkset->genNumber
|
||
|
||
|
||
//
|
||
// GenerateMessage(...)
|
||
//
|
||
// Allocates and initialises an OMNET_OPERATION_PKT of the specified type.
|
||
// Note that the <size> field is set to zero even if <messageType> is an
|
||
// add, update or replace. The QueueMessage function will set the size to
|
||
// the correct value when the message is queued.
|
||
//
|
||
UINT GenerateOpMessage( POM_WSGROUP pWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT_ID pObjectID,
|
||
POM_OBJECTDATA pData,
|
||
OMNET_MESSAGE_TYPE messageType,
|
||
POMNET_OPERATION_PKT * ppPacket);
|
||
|
||
|
||
//
|
||
//
|
||
// QueueMessage(...)
|
||
//
|
||
// This function creates a send instruction for the specified message and
|
||
// places the instruction on the specified send queue for the specified
|
||
// Domain. It them sends an event to ObMan prompting it to examine the
|
||
// queue.
|
||
//
|
||
//
|
||
|
||
UINT QueueMessage(PUT_CLIENT putTask,
|
||
POM_DOMAIN pDomain,
|
||
NET_CHANNEL_ID channelID,
|
||
NET_PRIORITY priority,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECT pObjectRec,
|
||
POMNET_PKT_HEADER pPacket,
|
||
POM_OBJECTDATA pData,
|
||
BOOL compressOrNot);
|
||
|
||
//
|
||
// GetMessageSize(...)
|
||
//
|
||
UINT GetMessageSize(OMNET_MESSAGE_TYPE messageType);
|
||
|
||
|
||
//
|
||
// PreProcessMessage(...)
|
||
//
|
||
UINT PreProcessMessage(POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT_ID pObjectID,
|
||
OMNET_MESSAGE_TYPE messageType,
|
||
POM_WSGROUP * ppWSGroup,
|
||
POM_WORKSET * ppWorkset,
|
||
POM_OBJECT * ppObjectRec);
|
||
|
||
|
||
//
|
||
//
|
||
// PurgeNonPersistent(...)
|
||
//
|
||
// Purges any objects added by <userID> from non-persistent worksets in the
|
||
// workset group identified by <wsGroupID> in the specified domain.
|
||
//
|
||
//
|
||
|
||
void PurgeNonPersistent(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID,
|
||
NET_UID userID);
|
||
|
||
//
|
||
// ProcessWorksetNew(...)
|
||
//
|
||
UINT ProcessWorksetNew(PUT_CLIENT putTask,
|
||
POMNET_OPERATION_PKT pPacket,
|
||
POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
// ProcessWorksetClear(...)
|
||
//
|
||
UINT ProcessWorksetClear(PUT_CLIENT putTask, POM_PRIMARY pomPrimary,
|
||
POMNET_OPERATION_PKT pPacket,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset);
|
||
|
||
|
||
//
|
||
// ProcessObjectAdd(...)
|
||
//
|
||
UINT ProcessObjectAdd(PUT_CLIENT putTask,
|
||
POMNET_OPERATION_PKT pPacket,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECTDATA pData,
|
||
POM_OBJECT * ppObj);
|
||
|
||
|
||
//
|
||
// ProcessObjectMove(...)
|
||
//
|
||
void ProcessObjectMove(PUT_CLIENT putTask,
|
||
POMNET_OPERATION_PKT pPacket,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECT pObjectRec);
|
||
|
||
|
||
//
|
||
// ProcessObjectDRU(...)
|
||
//
|
||
UINT ProcessObjectDRU(PUT_CLIENT putTask,
|
||
POMNET_OPERATION_PKT pPacket,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECT pObj,
|
||
POM_OBJECTDATA pData);
|
||
|
||
|
||
//
|
||
// ObjectAdd(...)
|
||
//
|
||
UINT ObjectAdd(PUT_CLIENT putTask, POM_PRIMARY pomPrimary,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECTDATA pData,
|
||
UINT updateSize,
|
||
OM_POSITION position,
|
||
OM_OBJECT_ID * pObjectID,
|
||
POM_OBJECT * ppObj);
|
||
|
||
|
||
|
||
|
||
//
|
||
// WSGroupEventPost(...)
|
||
//
|
||
// This function posts the specified event to all local Clients registered
|
||
// with the workset group. The <param2> parameter is the second parameter
|
||
// on the event to be posted.
|
||
//
|
||
//
|
||
|
||
UINT WSGroupEventPost(PUT_CLIENT putTaskFrom,
|
||
POM_WSGROUP pWSGroup,
|
||
BYTE target,
|
||
UINT event,
|
||
OM_WORKSET_ID worksetID,
|
||
UINT_PTR param2);
|
||
|
||
|
||
//
|
||
//
|
||
// This function is called by
|
||
//
|
||
// - OM_WorksetOpen, when a Client creates a new workset
|
||
//
|
||
// - ProcessLockRequest, when a lock request arrives for a workset we
|
||
// don't yet know about
|
||
//
|
||
// - xx, when an OMNET_WORKSET_NEW message arrives.
|
||
//
|
||
// It creates the local data structures for the workset and posts an event
|
||
// to all local Clients registered with the workset group.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// WorksetCreate(...)
|
||
//
|
||
// This function creates a new workset in the specified workset group.
|
||
//
|
||
// It calls GenerateMessage, ProcessWorksetNew and QueueMessage.
|
||
//
|
||
//
|
||
|
||
UINT WorksetCreate(PUT_CLIENT putTask,
|
||
POM_WSGROUP pWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
BOOL fTemp,
|
||
NET_PRIORITY priority);
|
||
|
||
|
||
//
|
||
//
|
||
// WorksetEventPost(...)
|
||
//
|
||
// This function posts the specified event to all local Clients which have
|
||
// the workset open (at most 1 Client in R1.1).
|
||
//
|
||
// The <putTask> parameter is the putTask of the invoking task (and NOT
|
||
// the handle of the task to post the event to).
|
||
//
|
||
// The number of Clients the event was successfully posted to is returned
|
||
// in *pNumPosts, if pNumPosts is not NULL. A caller which wishes to
|
||
// ignore the number of events posted can pass in NULL as the pNumPosts
|
||
// parameter.
|
||
//
|
||
//
|
||
|
||
UINT WorksetEventPost(PUT_CLIENT putTask,
|
||
POM_WORKSET pWorkset,
|
||
BYTE target,
|
||
UINT event,
|
||
POM_OBJECT pObj);
|
||
|
||
|
||
//
|
||
// WorksetDoClear(...)
|
||
//
|
||
void WorksetDoClear(PUT_CLIENT putTask,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_PENDING_OP pPendingOp);
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessLockRequest(...)
|
||
//
|
||
// This function is called when ObMan receives an OMNET_LOCK_REQ message
|
||
// from another node.
|
||
//
|
||
// If we
|
||
//
|
||
// - have the workset locked already, or
|
||
//
|
||
// - are trying to lock the workset and our MCS user ID is greater than the
|
||
// node which sent us the request,
|
||
//
|
||
// we deny the lock (i.e. send back a negative OMNET_LOCK_REPLY).
|
||
//
|
||
// In all other cases, we grant the lock (i.e. send back an affirmative
|
||
// OMNET_LOCK_REPLY).
|
||
//
|
||
// If we grant the lock to the remote node when we were trying to get it
|
||
// for ourselves, our attempt to lock the workset has failed so we call
|
||
// WorksetLockResult with a failure code.
|
||
//
|
||
//
|
||
|
||
void ProcessLockRequest(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POMNET_LOCK_PKT pLockReqPkt);
|
||
|
||
|
||
//
|
||
//
|
||
// QueueLockReply(...)
|
||
//
|
||
// This function is called when we have decided to grant or deny a lock
|
||
// request received from another node. It queues the appropriate response
|
||
// on ObMan's send queue.
|
||
//
|
||
//
|
||
|
||
void QueueLockReply(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OMNET_MESSAGE_TYPE result,
|
||
NET_CHANNEL_ID destination,
|
||
POMNET_LOCK_PKT pLockReqPkt);
|
||
|
||
|
||
//
|
||
//
|
||
// QueueLockNotify(...)
|
||
//
|
||
// Queues a LOCK_NOTIFY command on the broadcast channel for the workset
|
||
// group, indicating that we have granted the lock to the <locker>.
|
||
//
|
||
//
|
||
|
||
void QueueLockNotify(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
NET_UID locker);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessLockReply(...)
|
||
//
|
||
// This function is called when ObMan receives an OMNET_LOCK_GRANT or
|
||
// OMNET_LOCK_DENY message from another node, in response to an
|
||
// OMNET_LOCK_REQ message we sent out earlier.
|
||
//
|
||
// The function removes this node from the list of expected respondents for
|
||
// this lock (if it is in the list).
|
||
//
|
||
// If the list is now empty, the lock has succeeded so WorksetLockResult is
|
||
// called.
|
||
//
|
||
// Otherwise, nothing else happens for the moment.
|
||
//
|
||
//
|
||
|
||
void ProcessLockReply(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
NET_UID sender,
|
||
OM_CORRELATOR correlator,
|
||
OMNET_MESSAGE_TYPE replyType);
|
||
|
||
|
||
//
|
||
// PurgeLockRequests(...)
|
||
//
|
||
void PurgeLockRequests(POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessLockTimeout(...)
|
||
//
|
||
// This function is called when ObMan receives a lock timeout event. It
|
||
// checks to see if any of the nodes from whom we are still expecting lock
|
||
// replies have in fact gone away; if they have, it removes them from the
|
||
// list of expected respondents.
|
||
//
|
||
// If this list is now empty, the lock has succeeded and WorksetLockResult
|
||
// is called.
|
||
//
|
||
// If the list is not empty, then another delayed lock timeout event is
|
||
// posted to ObMan, unless we have already had the maximum number of
|
||
// timeouts for this lock, in which case the lock has failed and
|
||
// WorksetLockResult is called.
|
||
//
|
||
//
|
||
|
||
void ProcessLockTimeout(POM_PRIMARY pomPrimary,
|
||
UINT retriesToGo,
|
||
UINT callID);
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// WorksetLockReq(...)
|
||
//
|
||
// This function is called
|
||
//
|
||
// - by OM_WorksetLockReq, when a Client wants to lock a workset
|
||
//
|
||
// - by LockObManControl, when ObMan wants to lock workset #0 in
|
||
// ObManControl.
|
||
//
|
||
// The function decides whether the lock can be granted or refused
|
||
// synchronously, and if so calls WorksetLockResult. If not, it posts an
|
||
// OMINT_EVENT_LOCK_REQ event to the ObMan task, which results in the
|
||
// ProcessLocalLockRequest function being called later.
|
||
//
|
||
// The <hWSGroup> parameter is the workset group handle which will be
|
||
// included in the eventual OM_WORKSET_LOCK_CON event. Its value is not
|
||
// used in the function; when this function is called in the ObMan task
|
||
// this value is set to zero (since the ObMan task doesn't use workset
|
||
// group handles).
|
||
//
|
||
// On successful completion, the <pCorrelator> parameter points to the
|
||
// correlator value which will be included in the eventual
|
||
// OM_WORKSET_LOCK_CON event.
|
||
//
|
||
//
|
||
|
||
void WorksetLockReq(PUT_CLIENT putTask, POM_PRIMARY pomPrimary,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_CORRELATOR * pCorrelator);
|
||
|
||
|
||
//
|
||
//
|
||
// WorksetLockResult(...)
|
||
//
|
||
// This function is called when we have finished processing a request to
|
||
// obtain a workset lock. The function sets the workset state accordingly,
|
||
// posts an appropriate event to the task which requested the lock, and
|
||
// frees the lock request control block.
|
||
//
|
||
//
|
||
void WorksetLockResult(PUT_CLIENT putTask,
|
||
POM_LOCK_REQ * ppLockReq,
|
||
UINT result);
|
||
|
||
|
||
//
|
||
//
|
||
// BuildNodeList(...)
|
||
//
|
||
// This function builds a list of the remote nodes which are registered
|
||
// with the workset group referenced in the lock request CB passed in.
|
||
//
|
||
//
|
||
|
||
UINT BuildNodeList(POM_DOMAIN pDomain, POM_LOCK_REQ pLockReq);
|
||
|
||
|
||
//
|
||
//
|
||
// HandleMultLockReq(...)
|
||
//
|
||
// This function searches the global list of pending lock requests (stored
|
||
// in the root data structure) for any lock requests matching the Domain,
|
||
// workset group and workset specified.
|
||
//
|
||
//
|
||
|
||
void HandleMultLockReq(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
UINT result);
|
||
|
||
|
||
//
|
||
//
|
||
// FindLockReq(...)
|
||
//
|
||
// This function searches the global list of pending lock requests (stored
|
||
// in the root data structure) for a lock request that matches the Domain,
|
||
// workset group and workset specified.
|
||
//
|
||
// If found, a pointer to the lock request is returned in <ppLockReq>.
|
||
//
|
||
// It can search for a primary lock request if needed
|
||
//
|
||
//
|
||
|
||
void FindLockReq(POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_LOCK_REQ * ppLockreq,
|
||
BYTE lockType);
|
||
|
||
|
||
//
|
||
// ReleaseAllNetLocks(...)
|
||
//
|
||
void ReleaseAllNetLocks(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID,
|
||
NET_UID userID);
|
||
|
||
//
|
||
//
|
||
// ProcessUnlock(...)
|
||
//
|
||
// This function is called when an OMNET_UNLOCK message is received from
|
||
// the network. The function is a wrapper which just derives a workset
|
||
// pointer and calls ProcessUnlock (above).
|
||
//
|
||
//
|
||
|
||
void ProcessUnlock(POM_PRIMARY pomPrimary,
|
||
POM_WORKSET pWorkset,
|
||
NET_UID sender);
|
||
|
||
//
|
||
// WorksetUnlock(...)
|
||
//
|
||
void WorksetUnlock(PUT_CLIENT putTask, POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset);
|
||
|
||
//
|
||
// WorksetUnlockLocal(...)
|
||
//
|
||
void WorksetUnlockLocal(PUT_CLIENT putTask, POM_WORKSET pWorkset);
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// ObjectDoDelete(...)
|
||
//
|
||
// This function deletes an object in a workset. It is called by
|
||
//
|
||
// - OM_ObjectDeleteConfirm, when a Client confirms the deletion of an
|
||
// object.
|
||
//
|
||
// - WorksetDoClear, to delete each individual object
|
||
//
|
||
// - ProcessObjectDelete when ObMan receives a Delete message from the
|
||
// network for an object in a workset which no local Clients have open.
|
||
//
|
||
//
|
||
|
||
void ObjectDoDelete(PUT_CLIENT putTask,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECT pObj,
|
||
POM_PENDING_OP pPendingOp);
|
||
|
||
|
||
//
|
||
//
|
||
// ObjectDRU(...)
|
||
//
|
||
// This function generate, processes and queues a message of type DELETE,
|
||
// REPLACE or UPDATE (as specified by <type>).
|
||
//
|
||
//
|
||
UINT ObjectDRU(PUT_CLIENT putTask,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECT pObj,
|
||
POM_OBJECTDATA pData,
|
||
OMNET_MESSAGE_TYPE type);
|
||
|
||
|
||
//
|
||
//
|
||
// ObjectRead(...)
|
||
//
|
||
// This function converts an object handle to a pointer to the object data.
|
||
// An invalid handle causes an assertion failure.
|
||
//
|
||
//
|
||
|
||
void ObjectRead(POM_CLIENT pomClient,
|
||
POM_OBJECT pObj,
|
||
POM_OBJECTDATA * ppData);
|
||
|
||
|
||
//
|
||
// ObjectInsert(...)
|
||
//
|
||
void ObjectInsert(POM_WORKSET pWorkset,
|
||
POM_OBJECT pObj,
|
||
OM_POSITION position);
|
||
|
||
|
||
//
|
||
// ObjectDoMove(...)
|
||
//
|
||
void ObjectDoMove(POM_OBJECT pObjToMove,
|
||
POM_OBJECT pOtherObjectRec,
|
||
OM_POSITION position);
|
||
|
||
|
||
//
|
||
// ObjectDoUpdate(...)
|
||
//
|
||
void ObjectDoUpdate(PUT_CLIENT putTask,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECT pObj,
|
||
POM_PENDING_OP pPendingOp);
|
||
|
||
|
||
//
|
||
// ObjectDoReplace(...)
|
||
//
|
||
void ObjectDoReplace(PUT_CLIENT putTask,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECT pObj,
|
||
POM_PENDING_OP pPendingOp);
|
||
|
||
|
||
//
|
||
// ObjectIDToPtr(...)
|
||
//
|
||
UINT ObjectIDToPtr(POM_WORKSET pWorkset,
|
||
OM_OBJECT_ID objectID,
|
||
POM_OBJECT * ppObj);
|
||
|
||
|
||
|
||
//
|
||
// FindPendingOp(...)
|
||
//
|
||
void FindPendingOp(POM_WORKSET pWorkset,
|
||
POM_OBJECT pObj,
|
||
OM_OPERATION_TYPE type,
|
||
POM_PENDING_OP * ppPendingOp);
|
||
|
||
|
||
//
|
||
// WSGRecordFind(...)
|
||
//
|
||
void WSGRecordFind(POM_DOMAIN pDomain, OMWSG wsg, OMFP fpHandler,
|
||
POM_WSGROUP * ppWSGroup);
|
||
|
||
|
||
//
|
||
// DeterminePriority(...)
|
||
//
|
||
void DeterminePriority(NET_PRIORITY * pPriority,
|
||
POM_OBJECTDATA pData);
|
||
|
||
|
||
//
|
||
// RemoveClientFromWSGList(...)
|
||
//
|
||
// The second parameter is the putTask of the Client to be deregistered.
|
||
// It is NOT (well, not necessarily) the putTask of the calling task, and
|
||
// for this reason (to avoid it being used as such) is passed as a 32-bit
|
||
// integer.
|
||
//
|
||
void RemoveClientFromWSGList(
|
||
PUT_CLIENT putUs,
|
||
PUT_CLIENT putTask,
|
||
POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
// AddClientToWSGList(...)
|
||
//
|
||
UINT AddClientToWSGList(PUT_CLIENT putTask,
|
||
POM_WSGROUP pWSGroup,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
UINT mode);
|
||
|
||
|
||
//
|
||
// AddClientToWsetList(...)
|
||
//
|
||
UINT AddClientToWsetList(PUT_CLIENT putTask,
|
||
POM_WORKSET pWorkset,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
UINT mode,
|
||
POM_CLIENT_LIST * pClientListEntry);
|
||
|
||
|
||
//
|
||
// PostWorksetNewEvents(...)
|
||
//
|
||
UINT PostWorksetNewEvents(PUT_CLIENT putFrom,
|
||
PUT_CLIENT putTask,
|
||
POM_WSGROUP pWSGroup,
|
||
OM_WSGROUP_HANDLE hWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// QueueUnlock(...)
|
||
//
|
||
// This function queues a workset unlock packet for sending to the
|
||
// specified destination.
|
||
//
|
||
//
|
||
|
||
UINT QueueUnlock(PUT_CLIENT putTask,
|
||
POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID,
|
||
OM_WORKSET_ID worksetID,
|
||
NET_UID destination,
|
||
NET_PRIORITY priority);
|
||
|
||
//
|
||
// PurgeReceiveCBs(...)
|
||
//
|
||
void PurgeReceiveCBs(POM_DOMAIN pDomain,
|
||
NET_CHANNEL_ID channel);
|
||
|
||
|
||
//
|
||
// FreeSendInst()
|
||
//
|
||
void FreeSendInst(POM_SEND_INST pSendInst);
|
||
|
||
|
||
//
|
||
// SetPersonData(...)
|
||
//
|
||
UINT SetPersonData(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// FindInfoObject(...)
|
||
//
|
||
// This function searches workset #0 in the ObManControl workset group in
|
||
// the specified Domain for a matching info object.
|
||
//
|
||
// The match is performed as follows:
|
||
//
|
||
// - if functionProfile and wsGroupName are not NULL, the first object
|
||
// matching both is returned
|
||
//
|
||
// - if functionProfile is not NULL but wsGroupName is, the first object
|
||
// matching functionProfile is returned
|
||
//
|
||
// - if functionProfile is NULL, the first object matching wsGroupID is
|
||
// returned.
|
||
//
|
||
//
|
||
|
||
void FindInfoObject(POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID,
|
||
OMWSG wsg,
|
||
OMFP fpHandler,
|
||
POM_OBJECT * ppInfoObjectRec);
|
||
|
||
|
||
//
|
||
//
|
||
// FindPersonObject(...)
|
||
//
|
||
// This function searches the specified workset in ObManControl looking for
|
||
// a registration object which has
|
||
//
|
||
// - the same user ID as <userID>, if <searchType> == FIND_THIS
|
||
//
|
||
// - a different user ID from <userID>, if <searchType> == FIND_OTHERS.
|
||
//
|
||
//
|
||
|
||
void FindPersonObject(POM_WORKSET pOMCWorkset,
|
||
NET_UID userID,
|
||
UINT searchType,
|
||
POM_OBJECT * ppRegObjectRec);
|
||
|
||
#define FIND_THIS 1
|
||
#define FIND_OTHERS 2
|
||
|
||
//
|
||
// ProcessOMCWorksetNew(...)
|
||
//
|
||
void ProcessOMCWorksetNew(POM_PRIMARY pomPrimary, OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID);
|
||
|
||
|
||
//
|
||
// ProcessOMCObjectEvents(...)
|
||
//
|
||
void ProcessOMCObjectEvents(POM_PRIMARY pomPrimary,
|
||
UINT event,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj);
|
||
|
||
|
||
//
|
||
// GeneratePersonEvents(...)
|
||
//
|
||
void GeneratePersonEvents(POM_PRIMARY pomPrimary,
|
||
UINT event,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_OBJECT pObj);
|
||
|
||
|
||
//
|
||
// PostAddEvents(...)
|
||
//
|
||
UINT PostAddEvents(PUT_CLIENT putTaskFrom,
|
||
POM_WORKSET pWorkset,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
PUT_CLIENT putTaskTo);
|
||
|
||
|
||
//
|
||
// RemovePersonObject(...)
|
||
//
|
||
void RemovePersonObject(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID,
|
||
NET_UID detachedUserID);
|
||
|
||
|
||
//
|
||
// RemoveInfoObject(...)
|
||
//
|
||
void RemoveInfoObject(POM_PRIMARY pomPrimary, POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID);
|
||
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// DEBUG ONLY FUNCTIONS
|
||
//
|
||
// These functions are debug code only - for normal compilations, the
|
||
// declarations are #defined to nothing and the definitions are
|
||
// preprocessed out altogether.
|
||
//
|
||
//
|
||
|
||
#ifndef _DEBUG
|
||
|
||
#define CheckObjectCount(x, y)
|
||
#define CheckObjectOrder(x)
|
||
#define DumpWorkset(x, y)
|
||
|
||
#else // _DEBUG
|
||
|
||
//
|
||
//
|
||
// CheckConstants(...)
|
||
//
|
||
// The ObMan code relies on certain assumptions about the sizes and formats
|
||
// of various data structures, and the values of certain constants.
|
||
//
|
||
//
|
||
// The OMNET_OPERATION_PKT type has two one-byte fields, <position> and
|
||
// <flags>, which are used to hold
|
||
//
|
||
// - a NET_PRIORITY value which indicates the priority for the
|
||
// workset for WORKSET_NEW/WORKSET_CATCHUP messages, and
|
||
//
|
||
// - a UINT (the number of bytes being acknowledged) in the case
|
||
// of a DATA_ACK message.
|
||
//
|
||
// GenerateOpMessage and AckData cast the <position> field to a two-byte
|
||
// quantity for this purpose. Therefore, it is necessary that these two
|
||
// fields exist, that they are adjacent and that the <position> one
|
||
// comes first.
|
||
//
|
||
// In addition, since the priority information is a NET_PRIORITY, we
|
||
// must ensure that a NET_PRIORITY is indeed two bytes long.
|
||
//
|
||
//
|
||
// ASSERT((sizeof(NET_PRIORITY) == (2 * sizeof(BYTE))));
|
||
//
|
||
// ASSERT((offsetof(OMNET_OPERATION_PKT, position) + 1 ==
|
||
// offsetof(OMNET_OPERATION_PKT, flags)));
|
||
//
|
||
//
|
||
// In many places, for-loops use workset IDs as the loop variable and
|
||
// OM_MAX_WORKSETS_PER_WSGROUP as the end condition. To avoid infinite
|
||
// loops, this constant must be less than 256:
|
||
//
|
||
// ASSERT((OM_MAX_WORKSETS_PER_WSGROUP < 256));
|
||
//
|
||
// The OMC WSG has one workset for each WSG in the Domain. Since the
|
||
// number of worksets per WSG is limited, the # of WSGs per Domain is
|
||
// limited in the same way:
|
||
//
|
||
// ASSERT(OM_MAX_WSGROUPS_PER_DOMAIN <= OM_MAX_WORKSETS_PER_WSGROUP);
|
||
//
|
||
|
||
|
||
//
|
||
//
|
||
// CheckObjectCount(...)
|
||
//
|
||
// This function counts the number of non-deleted objects in the specified
|
||
// workset and compares this against the <numObjects> field of the workset
|
||
// record. A mismatch causes an assertion failure.
|
||
//
|
||
//
|
||
void CheckObjectCount(POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset);
|
||
|
||
//
|
||
// CheckObjectOrder(...)
|
||
//
|
||
void CheckObjectOrder(POM_WORKSET pWorkset);
|
||
|
||
|
||
#endif // _DEBUG
|
||
|
||
|
||
//
|
||
//
|
||
// WORKSET OPEN/CLOSE BITFIELD MANIPULATION MACROS
|
||
//
|
||
// ObMan maintains one usage record for each workset group a Client is
|
||
// registered with. One of the fields of the usage record is an 32-byte
|
||
// bitfield which is interpreted as an array of 256 booleans, indicating
|
||
// whether a Client has the corresponding workset open.
|
||
//
|
||
// These macros use the EXTRACT_BIT, SET_BIT and CLEAR_BIT macros to set and clear the bit
|
||
// for <worksetID> in the <worksetOpenFlags> bitfield of the usage record.
|
||
//
|
||
//
|
||
|
||
BOOL __inline WORKSET_IS_OPEN(POM_USAGE_REC pUsageRec, OM_WORKSET_ID worksetID)
|
||
{
|
||
return((pUsageRec->worksetOpenFlags[worksetID / 8] & (0x80 >> (worksetID % 8))) != 0);
|
||
}
|
||
|
||
void __inline WORKSET_SET_OPEN(POM_USAGE_REC pUsageRec, OM_WORKSET_ID worksetID)
|
||
{
|
||
pUsageRec->worksetOpenFlags[worksetID / 8] |= (0x80 >> (worksetID % 8));
|
||
}
|
||
|
||
void __inline WORKSET_SET_CLOSED(POM_USAGE_REC pUsageRec, OM_WORKSET_ID worksetID)
|
||
{
|
||
pUsageRec->worksetOpenFlags[worksetID / 8] &= ~(0x80 >> (worksetID % 8));
|
||
}
|
||
|
||
|
||
//
|
||
//
|
||
// ReleaseAllLocks(...)
|
||
//
|
||
// This function releases all the locks held by a particular Client for a
|
||
// particular workset. In R1.1, this is at most one lock (the workset
|
||
// lock) but if/when object locking is supported, this function will also
|
||
// release all object locks held.
|
||
//
|
||
// This function is closed when a Client is closing a workset.
|
||
//
|
||
//
|
||
|
||
void ReleaseAllLocks(POM_CLIENT pomClient,
|
||
POM_USAGE_REC pUsageRec,
|
||
POM_WORKSET pWorkset);
|
||
|
||
|
||
//
|
||
//
|
||
// ReleaseAllObjects(...)
|
||
//
|
||
// This function releases all the objects held by a particular Client in a
|
||
// particular workset.
|
||
//
|
||
// This function is called when a Client closes a workset.
|
||
//
|
||
void ReleaseAllObjects(POM_USAGE_REC pUsageRec, POM_WORKSET pWorkset);
|
||
|
||
|
||
//
|
||
//
|
||
// ConfirmAll(...)
|
||
//
|
||
// This function confirms any pending operations for the workset specified.
|
||
//
|
||
// The function is called when a Client closes a workset.
|
||
//
|
||
// Since this function may call WorksetDoClear, the caller must hold the
|
||
// workset group mutex.
|
||
//
|
||
//
|
||
|
||
void ConfirmAll(POM_CLIENT pomClient,
|
||
POM_USAGE_REC pUsageRec,
|
||
POM_WORKSET pWorkset);
|
||
|
||
|
||
//
|
||
//
|
||
// DiscardAllObjects(...)
|
||
//
|
||
// This function discards any objects allocated for the specified Client
|
||
// for the specified workset but so far unused.
|
||
//
|
||
// The function is called when a Client closes a workset.
|
||
//
|
||
//
|
||
void DiscardAllObjects(POM_USAGE_REC pUsageRec,
|
||
POM_WORKSET pWorkset);
|
||
|
||
|
||
//
|
||
//
|
||
// RemoveFromUnusedList
|
||
//
|
||
// This function removes an object (specified by a pointer to the object)
|
||
// from the Client's list of unused objects. It is called by
|
||
//
|
||
// - OM_ObjectAdd, OM_ObjectUpdate and OM_ObjectReplace when a
|
||
// Client inserts an object into a workset, or
|
||
//
|
||
// - OM_ObjectDiscard, when a Client discards an unused object.
|
||
//
|
||
//
|
||
|
||
void RemoveFromUnusedList(POM_USAGE_REC pUsageRec, POM_OBJECTDATA pData);
|
||
|
||
|
||
//
|
||
//
|
||
// OM_ObjectAdd(...)
|
||
//
|
||
// This function adds an object to a worksets, in the specified position.
|
||
//
|
||
// Although it is not strictly an API function, it performs full parameter
|
||
// validation and could be externalised easily.
|
||
//
|
||
//
|
||
|
||
UINT OM_ObjectAdd(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECTDATA * ppData,
|
||
UINT updateSize,
|
||
POM_OBJECT * ppObj,
|
||
OM_POSITION position);
|
||
|
||
|
||
//
|
||
//
|
||
// OM_ObjectMove(...)
|
||
//
|
||
// This function moves an object to the start or end of a workset. It is
|
||
// called by OM_ObjectMoveFirst and OM_ObjectMoveLast.
|
||
//
|
||
// Although it is not strictly an API function, it performs full parameter
|
||
// validation and could be externalised easily.
|
||
//
|
||
//
|
||
|
||
UINT OM_ObjectMove(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj,
|
||
OM_POSITION position);
|
||
|
||
|
||
//
|
||
//
|
||
// ValidateParamsX(...)
|
||
//
|
||
// These functions are used to validate parameters and convert them to
|
||
// various pointers, as follows:
|
||
//
|
||
// ValidateParams2 - checks pomClient, hWSGroup
|
||
// - returns pUsageRec, pWSGroup
|
||
//
|
||
// ValidateParams3 - checks pomClient, hWSGroup, worksetID,
|
||
// - returns pUsageRec, pWorkset
|
||
//
|
||
// Note: also asserts that workset is open
|
||
//
|
||
// ValidateParams4 - checks pomClient, hWSGroup, worksetID, pObj
|
||
//
|
||
// Each of the functions uses DCASSERT to bring down the calling task if an
|
||
// invalid parameter is detected.
|
||
//
|
||
//
|
||
|
||
__inline void ValidateParams2(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
UINT requiredMode,
|
||
POM_USAGE_REC * ppUsageRec,
|
||
POM_WSGROUP * ppWSGroup)
|
||
{
|
||
ValidateOMS(pomClient);
|
||
ASSERT(ValidWSGroupHandle(pomClient, hWSGroup));
|
||
|
||
*ppUsageRec = pomClient->apUsageRecs[hWSGroup];
|
||
ValidateUsageRec(*ppUsageRec);
|
||
ASSERT(requiredMode & (*ppUsageRec)->mode);
|
||
|
||
*ppWSGroup = (*ppUsageRec)->pWSGroup;
|
||
ValidateWSGroup(*ppWSGroup);
|
||
}
|
||
|
||
|
||
__inline void ValidateParams3(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
UINT requiredMode,
|
||
POM_USAGE_REC * ppUsageRec,
|
||
POM_WORKSET * ppWorkset)
|
||
{
|
||
POM_WSGROUP pWSGroup;
|
||
|
||
ValidateParams2(pomClient, hWSGroup, requiredMode, ppUsageRec, &pWSGroup);
|
||
|
||
ASSERT(WORKSET_IS_OPEN(*ppUsageRec, worksetID));
|
||
|
||
*ppWorkset = pWSGroup->apWorksets[worksetID];
|
||
ValidateWorkset(*ppWorkset);
|
||
}
|
||
|
||
|
||
__inline void ValidateParams4(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj,
|
||
UINT requiredMode,
|
||
POM_USAGE_REC * ppUsageRec,
|
||
POM_WORKSET * ppWorkset)
|
||
{
|
||
ValidateParams3(pomClient, hWSGroup, worksetID, requiredMode, ppUsageRec,
|
||
ppWorkset);
|
||
|
||
ValidateObject(pObj);
|
||
ASSERT(!(pObj->flags & DELETED));
|
||
}
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// SetUpUsageRecord(...)
|
||
//
|
||
UINT SetUpUsageRecord(POM_CLIENT pomClient,
|
||
UINT mode,
|
||
POM_USAGE_REC* ppUsageRec,
|
||
OM_WSGROUP_HANDLE * phWSGroup);
|
||
|
||
|
||
//
|
||
// FindUnusedWSGHandle()
|
||
//
|
||
UINT FindUnusedWSGHandle(POM_CLIENT pomClient, OM_WSGROUP_HANDLE * phWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// ObjectRelease(...)
|
||
//
|
||
// This function releases the specified Client's hold on the the specified
|
||
// object and removes the relevant entry from the Client's objects-in-use
|
||
// list.
|
||
//
|
||
// If <pObj> is NULL, the function releases the first object held by
|
||
// this Client in the specified workset, if any. If there are none, the
|
||
// function returns OM_RC_OBJECT_NOT_FOUND.
|
||
//
|
||
//
|
||
|
||
UINT ObjectRelease(POM_USAGE_REC pUsageRec,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj);
|
||
|
||
|
||
//
|
||
//
|
||
// WorksetClearPending(...)
|
||
//
|
||
// Look for a CLEAR_IND which is outstanding for the given workset which,
|
||
// when confirmed, will cause the given object to be deleted.
|
||
//
|
||
// Returns TRUE if such a CLEAR_IND is outstanding, FALSE otherwise.
|
||
//
|
||
//
|
||
|
||
BOOL WorksetClearPending(POM_WORKSET pWorkset, POM_OBJECT pObj);
|
||
|
||
|
||
|
||
|
||
UINT OM_Register(PUT_CLIENT putTask, OMCLI omClient, POM_CLIENT * ppomClient);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function registers a DC-Groupware task as an ObMan Client. A task
|
||
// must be a registered ObMan Client in order to call any of the other API
|
||
// functions.
|
||
//
|
||
// On successful completion, the value at <ppomClient> is this Client's ObMan
|
||
// handle, which must be passed as a parameter to all other API functions.
|
||
//
|
||
// This function registers an event handler and an exit procedure for the
|
||
// Client, so Clients must have previously registered fewer than the maximum
|
||
// number of Utility Service event handlers and exit procedures.
|
||
//
|
||
// If the are too many Clients already registered with ObMan, an error is
|
||
// returned.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_TOO_MANY_CLIENTS
|
||
//
|
||
//
|
||
|
||
void OM_Deregister(POM_CLIENT * ppomCient);
|
||
void CALLBACK OMSExitProc(LPVOID pomClient);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function deregisters an ObMan Client.
|
||
//
|
||
// On completion, the ObMan handle which the Client was using becomes
|
||
// invalid and the value at <ppomClient> is set to NULL to prevent the task
|
||
// from using it again.
|
||
//
|
||
// This function deregisters the Client from any workset groups with which
|
||
// it was registered.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
UINT OM_WSGroupRegisterPReq(POM_CLIENT pomClient,
|
||
UINT call,
|
||
OMFP fpHandler,
|
||
OMWSG wsg,
|
||
OM_CORRELATOR * pCorrelator);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This is an asynchronous function which requests that ObMan register a
|
||
// Client with a particular workset group for PRIMARY access. The workset
|
||
// group is determined by the following:
|
||
//
|
||
// - <call> is the DC-Groupware Call which contains/is to contain the
|
||
// workset group (or OM_NO_CALL if the workset group is/is to
|
||
// be a local workset group)
|
||
//
|
||
// - <functionProfile> is the Function Profile for the workset group
|
||
//
|
||
// - <wsGroupName> is the name of the workset group.
|
||
//
|
||
// The <pomClient> parameter is the ObMan handle returned by the OM_Register
|
||
// function.
|
||
//
|
||
// If a Client wishes to create a new, or register with an existing, workset
|
||
// group which exists only on the local machine, the value OM_NO_CALL should
|
||
// be specified for the <call> parameter. Workset groups created in this
|
||
// way for purely local use may be subsequently transferred into a call by
|
||
// invoking OM_WSGroupMoveReq at some later time.
|
||
//
|
||
// If this function completes successfully, the Client will subsequently
|
||
// receive an OM_WSGROUP_REGISTER_CON event indicating the success or
|
||
// failure of the registration.
|
||
//
|
||
// Registering with a workset group is a prerequisite to opening any of its
|
||
// worksets.
|
||
//
|
||
// If no workset group with this name and function profile exists in the
|
||
// specified call (or locally, if OM_NO_CALL specified), a new, empty
|
||
// workset group is created and assigned <wsGroupName> as its name. This
|
||
// name must be a valid workset group name.
|
||
//
|
||
// If the workset group already exists in the Call, its contents are copied
|
||
// from another node. This data transfer is made at low priority (note that
|
||
// subsequent receipt of the OM_WSGROUP_REGISTER_CON event does not indicate
|
||
// that this data transfer has completed).
|
||
//
|
||
// If there are worksets existing in the workset group, the Client will
|
||
// receive one or more OM_WORKSET_NEW_IND events after receiving the
|
||
// OM_WSGROUP_REGISTER_CON event.
|
||
//
|
||
// Note also that the contents of the workset group may be copied to this
|
||
// node in any order. Therefore, if objects in a workset reference other
|
||
// objects, the Client should not assume that the referenced object is
|
||
// present locally once the reference arrives.
|
||
//
|
||
// Clients registered for primary access to a workset group have full read
|
||
// and write access to the workset group and have a responsilibity to
|
||
// confirm destructive operations (such as workset clear and object delete,
|
||
// update and replace operations), as described in the relevant sections
|
||
// below.
|
||
//
|
||
// At most one Client per node may be registered with a given workset group
|
||
// for primary access. If a second Client attempts to register for primary
|
||
// access, OM_RC_TOO_MANY_CLIENTS is returned asynchronously via the
|
||
// OM_WSGROUP_REGISTER_CON event.
|
||
//
|
||
// On successful completion of the function, the return parameter
|
||
// <pCorrelator> points to a value which may be used by the Client to
|
||
// correlate this call with the event it generates. Notification of a
|
||
// successful registration will contain a workset group handle which the
|
||
// Client must uses subsequently when invoking other ObMan functions
|
||
// relating to this workset group.
|
||
//
|
||
// If the maximum number of workset groups in concurrent use per call has
|
||
// been reached, the OM_RC_TOO_MANY_WSGROUPS error is returned
|
||
// asynchronously. If the maximum number of workset groups in use by one
|
||
// Client is reached, OM_RC_NO_MORE HANDLES is returned synchronously. If
|
||
// ObMan cannot create a new workset group for any other reason, the
|
||
// OM_RC_CANNOT_CREATE_WSG error is returned (synchronously or
|
||
// asynchronously).
|
||
//
|
||
// Note that separate DC-Groupware tasks must each register independently
|
||
// with the workset groups they wish to use, as workset group handles may
|
||
// not be passed between tasks.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// Invoking this function will cause the OM_WSGROUP_REGISTER_CON event to be
|
||
// posted to the invoking Client.
|
||
//
|
||
// If ObMan is forced at some later stage to move the workset group out of
|
||
// the call for which it was intended (usually at call end time), the Client
|
||
// will receive an OM_WSGROUP_MOVE_IND event.
|
||
//
|
||
// When a Client has successfully registered with a workset group, it will
|
||
// receive OM_PERSON_JOINED_IND, OM_PERSON_LEFT_IND and
|
||
// OM_PERSON_DATA_CHANGED_IND events as primaries (including the calling
|
||
// Client) register and deregister from the workset group and change their
|
||
// person data.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_NO_MORE_HANDLES
|
||
//
|
||
//
|
||
|
||
UINT OM_WSGroupRegisterS(POM_CLIENT pomClient,
|
||
UINT call,
|
||
OMFP fpHandler,
|
||
OMWSG wsg,
|
||
OM_WSGROUP_HANDLE * phWSGroup);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This is a synchronous function which requests that ObMan register a
|
||
// Client with a particular workset group for SECONDARY access. The workset
|
||
// group is determined by the following:
|
||
//
|
||
// - <call> is the DC-Groupware call which contains the workset group (or
|
||
// OM_NO_CALL if the workset group is a local workset group)
|
||
//
|
||
// - <functionProfile> is the Function Profile of the workset group
|
||
//
|
||
// - <wsGroupName> is the name of the workset group.
|
||
//
|
||
// The <pomClient> parameter is the ObMan handle returned by the OM_Register
|
||
// function.
|
||
//
|
||
// A Client may only register for secondary access for a workset group when
|
||
// there is already a local Client fully registered for primary access to
|
||
// that workset group. If there is no such local primary, OM_RC_NO_PRIMARY
|
||
// is returned.
|
||
//
|
||
// If there are worksets existing in the workset group, the Client will
|
||
// receive one or more OM_WORKSET_NEW_IND events after this function
|
||
// completes.
|
||
//
|
||
// Registering for secondary access to a workset group gives a Client the
|
||
// same access privileges as a primary Client except for:
|
||
//
|
||
// - creating worksets
|
||
//
|
||
// - moving workset groups into/out of Calls
|
||
//
|
||
// - locking worksets and objects
|
||
//
|
||
// In addition, secondary Clients of a workset group will receive events
|
||
// relating to the workset group in the same way as primary Clients.
|
||
// However, the following important difference applies: secondary Clients
|
||
// will receive notification of object deletes, updates and replaces AFTER
|
||
// the associated operations have taken place (as opposed to primary
|
||
// Clients, who are informed BEFORE action is taken and must invoke the
|
||
// relevant confirmation function).
|
||
//
|
||
// To highlight this difference, these events have a primary and a secondary
|
||
// variety:
|
||
//
|
||
//
|
||
//
|
||
// Primary Secondary
|
||
//
|
||
// - OM_WORKSET_CLEAR_IND OM_WORKSET_CLEARED_IND
|
||
// - OM_OBJECT_DELETE_IND OM_OBJECT_DELETED_IND
|
||
// - OM_OBJECT_REPLACE_IND OM_OBJECT_REPLACED_IND
|
||
// - OM_OBJECT_UPDATE_IND OM_OBJECT_UPDATED_IND
|
||
//
|
||
//
|
||
//
|
||
// Several Clients per node, up to a defined limit, may be registered with
|
||
// a given workset group for secondary access. Once this limit is reached,
|
||
// OM_RC_TOO_MANY_CLIENTS is returned.
|
||
//
|
||
// On successful completion of the function, the return parameter
|
||
// <phWSGoup> points to a workset group handle which the Client must uses
|
||
// subsequently when invoking other ObMan functions relating to this
|
||
// workset group.
|
||
//
|
||
// Note that separate DC-Groupware tasks must each register independently
|
||
// with the workset groups they wish to use, as workset group handles may
|
||
// not be passed between tasks.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_NO_MORE_HANDLES
|
||
// OM_RC_NO_PRIMARY
|
||
// OM_RC_TOO_MANY_CLIENTS
|
||
//
|
||
//
|
||
|
||
UINT OM_WSGroupMoveReq(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
UINT callID,
|
||
OM_CORRELATOR * pCorrelator);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function requests that ObMan move a local workset group previously
|
||
// created as a local workset group (i.e. created specifying the OM_NO_CALL
|
||
// for the Call ID parameter) into the DC-Groupware Call identified by
|
||
// <callID>. If the move is successful, the workset group becomes available
|
||
// at all nodes in the Call.
|
||
//
|
||
// The workset group to move is specified by <hWSGroup>, which must be a
|
||
// valid workset group handle.
|
||
//
|
||
// If the function completes successfully, the OM_WSGROUP_MOVE_CON event is
|
||
// posted to the Client when the attempt to move the workset group into the
|
||
// Call has completed. This event indicates whether the attempt was
|
||
// successful.
|
||
//
|
||
// If there is already a (different) workset group in the specified Call
|
||
// with the same name and Function Profile, this function will fail
|
||
// asynchronously.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// Invoking this function causes the OM_WSGROUP_MOVE_CON to be posted to the
|
||
// invoking Client. If the move is successful, the OM_WSGROUP_MOVE_IND
|
||
// event is also posted to all local Clients which are registered with the
|
||
// workset group, including the invoking Client.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// OM_RC_ALREADY_IN_CALL
|
||
// Utility Service return codes
|
||
//
|
||
//
|
||
|
||
void OM_WSGroupDeregister(POM_CLIENT pomClient, OM_WSGROUP_HANDLE * phWSGroup);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function deregisters the Client from the workset group specified by
|
||
// the handle at <phWSGroup>. Any worksets which the Client had open in
|
||
// the workset group are closed (thereby releasing all locks), and the
|
||
// Client will receive no more events relating to this workset group.
|
||
//
|
||
// This call may cause the local copy of the workset group and its worksets
|
||
// to be discarded; in this sense, this function is destructive.
|
||
//
|
||
// This call sets the value at <phWSGroup> to NULL to prevent the Client
|
||
// using this handle in further calls to ObMan.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
UINT OM_WorksetOpenPReq(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
NET_PRIORITY priority,
|
||
BOOL fTemp,
|
||
OM_CORRELATOR * pCorrelator);
|
||
|
||
UINT OM_WorksetOpenS(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// These functions open a specified workset for a Client.
|
||
//
|
||
// OM_WorksetOpenPReq is an asynchronous function which will create the
|
||
// workset if it does not exist. Only primary Clients of this workset group
|
||
// may call this function.
|
||
//
|
||
// OM_WorksetOpenS is a synchronous function which will return
|
||
// OM_RC_WORKSET_DOESNT_EXIST if the workset does not exist. Only secondary
|
||
// Clients of this workset group may call this function.
|
||
//
|
||
// In the asynchronous (primary) case, when ObMan has opened the workset for
|
||
// the Client, or failed to do so, it posts an OM_WORKSET_OPEN_CON event to
|
||
// the Client indicating success or the reason for failure. This event will
|
||
// contain the correlator value returned in <pCorrelator> by this function.
|
||
//
|
||
// If this action results in the creation of a new workset, <priority> will
|
||
// specify the MCS priority at which data relating to the workset will be
|
||
// transmitted. Note that NET_TOP_PRIORITY is reserved for ObMan's private
|
||
// use and must not be specified as the <priority> parameter.
|
||
//
|
||
// If OM_OBMAN_CHOOSES_PRIORITY is specified as the <priority> parameter,
|
||
// ObMan will prioritise data transfers according to size.
|
||
//
|
||
// If the workset already exists, the Client will receive an
|
||
// OM_OBJECT_ADD_IND event for each object that is in the workset when it is
|
||
// opened.
|
||
//
|
||
// Opening a workset is a prerequisite to performing any operations on it or
|
||
// its contents. Once a Client has opened a workset it will receive events
|
||
// when changes are made to the workset or its contents.
|
||
//
|
||
// If this Client has already opened this workset,
|
||
// OM_RC_WORKSET_ALREADY_OPEN is returned. No 'use count' of opens is
|
||
// maintained, so the first OM_WorksetClose will close the workset,
|
||
// irrespective of how many times it has been opened.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// Invoking OM_WorksetOpenPReq causes the OM_WORKSET_OPEN_CON event to be
|
||
// posted to the invoking Client.
|
||
//
|
||
// If this action results in the creation of a new workset, an
|
||
// OM_WORKSET_NEW_IND is posted to all Clients which are registered with the
|
||
// workset group, including the invoking Client.
|
||
//
|
||
// In both the primary and secondary cases, if the workset contains any
|
||
// objects, an OM_OBJECT_ADD_IND event will be posted to the Client for each
|
||
// one.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_WORKSET_DOESNT_EXIST
|
||
// OM_RC_WORKSET_ALREADY_OPEN
|
||
//
|
||
//
|
||
|
||
#define OM_OBMAN_CHOOSES_PRIORITY (NET_INVALID_PRIORITY)
|
||
|
||
|
||
void OM_WorksetClose(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function closes the workset in <hWSGroup> identified by <worksetID>.
|
||
// The Client may no longer access this workset and will receive no more
|
||
// events relating to it. ObMan will however continue to update the
|
||
// contents of the workset in the background; in this sense, this function
|
||
// is non-destructive.
|
||
//
|
||
// When a Client closes a workset, ObMan automatically releases the
|
||
// following resources:
|
||
//
|
||
// - any locks the Client has relating to this workset
|
||
//
|
||
// - any objects which the Client had been reading or had allocated
|
||
// for writing in the workset.
|
||
//
|
||
// If indication events which require a Confirm function to be invoked have
|
||
// been received by the Client but not yet confirmed, these Confirms are
|
||
// implicitly executed by ObMan AND THE CLIENT MUST NOT SUBSEQUENTLY ATTEMPT
|
||
// TO CONFIRM THEM.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
void OM_WorksetFlowQuery(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
UINT* pBytesOutstanding);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// A Client calls this function whenever it wishes to discover the size of
|
||
// the backlog of data relating to the workset identified by <hWSGroup> and
|
||
// <worksetID>.
|
||
//
|
||
// The "backlog" is defined as the total number of bytes of object data
|
||
// which ObMan has been given by its local Clients and which have not yet
|
||
// been acknowledged by all remote nodes where there are Clients registered
|
||
// with the workset group.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
UINT OM_WorksetLockReq(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
OM_CORRELATOR * pCorrelator);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This is an asynchronous function which requests a lock for the workset in
|
||
// <hWSGroup> identified by <worksetID>. When ObMan has processed the lock
|
||
// request, it will send an OM_WORKSET_LOCK_CON event to the Client
|
||
// indicating success or the reason for failure.
|
||
//
|
||
// Holding a workset lock prevents other Clients from making any changes to
|
||
// the workset or any of its objects. Specifically, the following functions
|
||
// are prohibited:
|
||
//
|
||
// - locking the same workset
|
||
//
|
||
// - locking an object in the workset
|
||
//
|
||
// - moving an object within the workset
|
||
//
|
||
// - adding an object to the workset
|
||
//
|
||
// - deleting an object from the workset
|
||
//
|
||
// - updating or replacing an object in the workset.
|
||
//
|
||
// Locking a workset does not prevent other Clients from reading its
|
||
// contents.
|
||
//
|
||
// The function will cause an assertion failure if the Client requesting the
|
||
// lock already holds or has requested a lock which is equal to or after
|
||
// this one in the Universal Locking Order.
|
||
//
|
||
// On successful completion of the function, the value at <pCorrelator> is a
|
||
// value which the Client can use to correlate the subsequent
|
||
// OM_OBJECT_LOCK_CON event with this request.
|
||
//
|
||
// A Client must release the lock when it no longer needs it, using the
|
||
// OM_WorksetUnlock function. Locks will be automatically released when a
|
||
// Client closes the workset or deregisters from the workset group.
|
||
//
|
||
// Only primary Clients of a workset group may call this function.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// Invoking this function will cause the OM_WORKSET_LOCK_CON event to be
|
||
// posted to the invoking Client at some later time.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
//
|
||
//
|
||
|
||
void OM_WorksetUnlock(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function unlocks the workset in <hWSGroup> identified by
|
||
// <worksetID>. This must be the lock most recently acquired or requested
|
||
// by the Client; otherwise, the lock violation error causes an assertion
|
||
// failure.
|
||
//
|
||
// If this function is called before the OM_WORKSET_LOCK_CON event is
|
||
// received, the Client will not subsequently receive the event.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// This function causes an OM_WORKSET_UNLOCK_IND to be posted to all Clients
|
||
// which have the workset open, including the invoking Client.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
void OM_WorksetCountObjects(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
UINT* pCount);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// On successful completion of this function , the value at <pCount> is the
|
||
// number of objects in the workset in <hWSGroup> identified by
|
||
// <worksetID>.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
UINT OM_WorksetClear(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function requests that ObMan clear (i.e. delete the contents of)
|
||
// the workset in <hWSGroup> identified by <worksetID>.
|
||
//
|
||
// When this function is invoked, all Clients with the workset open
|
||
// (including the invoking Client) are notified of the impending clear via
|
||
// the OM_WORKSET_CLEAR_IND event. In response, each Client must invoke the
|
||
// OM_WorksetClearConfirm function; its view of the workset will not be
|
||
// cleared until it has done so.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// This function will result in the OM_WORKSET_CLEAR_IND being posted to all
|
||
// Clients which have the workset open, including the invoking Client.
|
||
//
|
||
// Return Codes
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_WORKSET_EXHAUSTED
|
||
//
|
||
//
|
||
|
||
void OM_WorksetClearConfirm(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// A Client must call this function after it receives an
|
||
// OM_WORKSET_CLEAR_IND. When the function is invoked, ObMan clears this
|
||
// Client's view of the workset. It is bad Groupware programming practice
|
||
// for a Client to unduly delay invoking this function.
|
||
//
|
||
// Note however that this function has a purely local effect: delaying (or
|
||
// executing) a clear confirm at one node will not affect the contents of
|
||
// the workset group at any other node.
|
||
//
|
||
// It is illegal to call this function when a Client has not received an
|
||
// OM_WORKSET_CLEAR_IND event.
|
||
//
|
||
// The arguments to the function must be the same as the workset group
|
||
// handle and workset ID included with the OM_WORKSET_CLEAR_IND event.
|
||
//
|
||
// The function will fail if ObMan is not expecting a clear-confirmation for
|
||
// this workset.
|
||
//
|
||
// This function causes all objects being read in this workset, and all
|
||
// object locks in this workset, to be released (i.e. the function performs
|
||
// implicit OM_ObjectUnlock and OM_ObjectRelease functions). It does not
|
||
// cause objects allocated using OM_ObjectAlloc to be discarded.
|
||
//
|
||
// If there are indication events for object Deletes, Replaces or Confirms
|
||
// which have been posted to the Client but not yet confirmed, these
|
||
// confirmations are implicitly executed.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// When the primary Client of a workset group confirms a clear using this
|
||
// function, an OM_WORKSET_CLEARED_IND is posted to all local secondary
|
||
// Clients of the workset group.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// These functions add an object to the workset in <hWSGroup> identified by
|
||
// <worksetID>. The <ppObject> parameter is a pointer to a pointer to the
|
||
// object.
|
||
//
|
||
// The position to add the object is determined as follows:
|
||
//
|
||
// - OM_ObjectAddLast: after the last object in the workset
|
||
//
|
||
// - OM_ObjectAddFirst: before the first object in the workset
|
||
//
|
||
// - OM_ObjectAddAfter: after the object specified by <hExistingObject>
|
||
//
|
||
// - OM_ObjectAddBefore: before the object specified by <hExistingObject>.
|
||
//
|
||
// Note that the OM_ObjectAddAfter and OM_ObjectAddBefore functions require
|
||
// that the invoking Client holds a workset lock, whereas the
|
||
// OM_ObjectAddFirst and OM_ObjectAddLast functions will fail if the workset
|
||
// is locked by another Client.
|
||
//
|
||
// ------------------------------------------------------------------------
|
||
//
|
||
// Note: OM_ObjectAddAfter and OM_ObjectAddBefore are not implemented in
|
||
// DC-Groupware R1.1.
|
||
//
|
||
// ------------------------------------------------------------------------
|
||
//
|
||
// On successful completion of the function, <phNewObject> points to the
|
||
// newly created handle of the object added. The Client should use this
|
||
// handle in all subsequent ObMan calls relating to this object.
|
||
//
|
||
// The <ppObject> parameter must be a pointer to a valid object pointer
|
||
// returned by the OM_ObjectAlloc function. If the function completes
|
||
// successfully, ObMan assumes ownership of the object and the value at
|
||
// <ppObject> is set to NULL to prevent the Client using the object pointer
|
||
// again.
|
||
//
|
||
// The <updateSize> parameter is the size (in bytes) of that portion of the
|
||
// object which may be updated using the OM_ObjectUpdate function (not
|
||
// counting the <length> field).
|
||
//
|
||
// Additions to a workset will be sequenced identically at all nodes which
|
||
// have the workset open, but the actual sequence arising from simultaneous
|
||
// additions by multiple Clients cannot be predicted in advance.
|
||
//
|
||
// If a set of Clients wishes to impose a particular sequence, they can
|
||
// enforce this using an agreed locking protocol based on the workset
|
||
// locking (in most cases, it is only necessary that the order is the same
|
||
// everywhere, which is why locking is not enforced by ObMan).
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// This function causes an OM_OBJECT_ADD_IND to be posted to all Clients
|
||
// which have the workset open, including the invoking Client.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_WORKSET_LOCKED (AddFirst, AddLast only)
|
||
// OM_RC_WORKSET_EXHAUSTED
|
||
//
|
||
//
|
||
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// These functions move an object within a workset. The workset is
|
||
// specified by <worksetID> and <hWSGroup> and the handle of the object to
|
||
// be moved is specified by <pObj>
|
||
//
|
||
// The position to which the object is moved is determined as follows:
|
||
//
|
||
// - OM_ObjectMoveLast: after the last object in the workset
|
||
//
|
||
// - OM_ObjectMoveFirst: before the first object in the workset
|
||
//
|
||
// - OM_ObjectMoveAfter: after the object specified by <pObj2>
|
||
//
|
||
// - OM_ObjectMoveBefore: before the object specified by <pObj2>.
|
||
//
|
||
// Note that OM_ObjectMoveAfter and OM_ObjectMoveBefore require that the
|
||
// invoking Client holds a workset lock, whereas the OM_ObjectMoveFirst and
|
||
// OM_ObjectMoveLast functions will fail if the workset is locked by another
|
||
// Client.
|
||
//
|
||
// ------------------------------------------------------------------------
|
||
//
|
||
// Note: OM_ObjectMoveAfter and OM_ObjectMoveBefore are not implemented in
|
||
// DC-Groupware R1.1.
|
||
//
|
||
// ------------------------------------------------------------------------
|
||
//
|
||
// Locked objects may be moved.
|
||
//
|
||
// Neither the handle nor the ID of an object is altered by moving it within
|
||
// a workset.
|
||
//
|
||
// Ensuing Events
|
||
//
|
||
// This action causes the OM_OBJECT_MOVE_IND to be posted to all Clients
|
||
// which have the workset open, including the invoking Client.
|
||
//
|
||
// Return Codes
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_WORKSET_EXHAUSTED
|
||
// OM_RC_WORKSET_LOCKED (MoveFirst, MoveLast only)
|
||
//
|
||
//
|
||
|
||
UINT OM_ObjectDelete(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function requests that ObMan delete an object from a workset. The
|
||
// workset is specified by <worksetID> and <hWSGroup> and the handle of the
|
||
// object to be deleted is <pObj>.
|
||
//
|
||
// The local copy of the object is not actually deleted until the Client
|
||
// invokes OM_ObjectDeleteConfirm in response to the OM_OBJECT_DELETE_IND
|
||
// event which this function generates.
|
||
//
|
||
// When this function is invoked, all Clients with the workset open
|
||
// (including the invoking Client) are notified of the impending deletion
|
||
// via the OM_OBJECT_DELETE_IND event. In response, each Client must invoke
|
||
// the OM_ObjectDeleteConfirm function; each Client will have access to the
|
||
// object until it has done so.
|
||
//
|
||
// If this object is already pending deletion (i.e. a DELETE_IND event has
|
||
// been posted to the Client but not yet Confirmed) this function returns
|
||
// the OM_RC_OBJECT_DELETED error.
|
||
//
|
||
// ObMan guarantees not to reuse a discarded object handle in the same
|
||
// workset within the lifetime of the workset group.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// This function causes the OM_OBJECT_DELETE_IND to be posted to all Clients
|
||
// which have the workset open, including the invoking Client (except as
|
||
// where stated above).
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_WORKSET_LOCKED
|
||
// OM_RC_WORKSET_EXHAUSTED
|
||
// OM_RC_OBJECT_DELETED
|
||
//
|
||
//
|
||
|
||
void OM_ObjectDeleteConfirm(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// A Client must call this function after it receives an
|
||
// OM_OBJECT_DELETE_IND. When the function is invoked, ObMan deletes the
|
||
// object specified by <hWSGroup>, <worksetID> and the value at <ppObj>.
|
||
// It is bad Groupware programming practice for a Client to unduly delay
|
||
// invoking this function.
|
||
//
|
||
// Note however that this function has a purely local effect: delaying (or
|
||
// executing) a delete confirm at one node will not affect the contents of
|
||
// the workset group at any other node.
|
||
//
|
||
// On successful completion, the handle of the deleted object becomes
|
||
// invalid and the value at <ppObj> is set to NULL to prevent the Client
|
||
// from further accessing this object.
|
||
//
|
||
// Any pointer to the previous version of this object which the Client had
|
||
// obtained using OM_ObjectRead becomes invalid and should not be referred
|
||
// to again (i.e. the function performs an implicit OM_ObjectRelease).
|
||
//
|
||
// The function will cause an assertion failure if ObMan is not expecting a
|
||
// delete-confirmation for this object.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// When the primary Client of a workset group confirms a delete using this
|
||
// function, an OM_OBJECT_DELETED_IND is posted to all local secondary
|
||
// Clients of the workset group.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
UINT OM_ObjectReplace(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj,
|
||
POM_OBJECTDATA * ppData);
|
||
|
||
UINT OM_ObjectUpdate(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj,
|
||
POM_OBJECTDATA * ppData);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function requests that ObMan replaces/updates the object specified
|
||
// by <pObj> in the workset specified by <worksetID> and <hWSGroup>.
|
||
//
|
||
// "Replacing" one object with another causes the previous object to be
|
||
// lost. "Updating" an object causes only the first N bytes of the object
|
||
// to be replaced by the <data> field of the object supplied, where N is the
|
||
// <length> field of the update. The rest of the object data remains the
|
||
// same, as does the length of the object.
|
||
//
|
||
// The local copy of the object is not actually replaced/updated until the
|
||
// Client invokes OM_ObjectReplaceConfirm/OM_ObjectUpdateConfirm in response
|
||
// to the OM_OBJECT_REPLACE_IND/OM_OBJECT_UPDATE_IND which this function
|
||
// generates.
|
||
//
|
||
// The <ppObject> parameter must be a pointer to a valid object pointer
|
||
// returned by the OM_ObjectAlloc function. If the function completes
|
||
// successfully, ObMan assumes ownership of the object and the value at
|
||
// <ppObject> is set to NULL to prevent the Client using the object pointer
|
||
// again.
|
||
//
|
||
// Neither the handle nor the ID of an object is altered by replacing or
|
||
// updating the object.
|
||
//
|
||
// If the object is pending deletion i.e. if ObMan has posted an
|
||
// OM_OBJECT_DELETE_IND event which has not yet been confirmed, the
|
||
// OM_RC_OBJECT_DELETED error is returned.
|
||
//
|
||
// If the object is pending replace or update i.e. if ObMan has posted an
|
||
// OM_OBJECT_REPLACE_IND/OM_OBJECT_UPDATE_IND event which has not yet been
|
||
// confirmed, this replace/update spoils the previous one. In this case, no
|
||
// further event is posted, and when the outstanding event is confirmed, the
|
||
// most recent replace/update is performed.
|
||
//
|
||
// The <reserved> parameter to OM_ObjectUpdate is not used in DC-Groupware
|
||
// R1.1 and must be set to zero.
|
||
//
|
||
// For a replace, the size of the object specified by <ppObject> must be at
|
||
// least as large as the <updateSize> specified when the object was
|
||
// originally added.
|
||
//
|
||
// For an update, the size of the object specified by <ppObject> must be the
|
||
// same as the <updateSize> specified when the object was originally added.
|
||
//
|
||
// Object replaces/updates will be sequenced identically at all nodes, but
|
||
// the actual sequence arising from simultaneous replace/update operations
|
||
// by multiple Clients cannot be predicted in advance.
|
||
//
|
||
// If a set of Clients wishes to impose a particular sequence, they should
|
||
// use an agreed locking protocol based on object or workset locking (in
|
||
// most cases, it is only necessary that the order is the same everywhere,
|
||
// which is why locking is not enforced by ObMan).
|
||
//
|
||
// Replaces and updates may be spoiled by ObMan so Client should not assume
|
||
// that an event will be generated for each replace or update carried out.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// This function causes the OM_OBJECT_REPLACE_IND/OM_OBJECT_UPDATE_IND to be
|
||
// posted to all Clients which have the workset open, including the invoking
|
||
// Client.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_WORKSET_LOCKED
|
||
// OM_RC_OBJECT_LOCKED
|
||
// OM_RC_OBJECT_DELETED
|
||
//
|
||
//
|
||
|
||
void OM_ObjectReplaceConfirm(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj);
|
||
|
||
void OM_ObjectUpdateConfirm(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// When a Client receives an OM_OBJECT_REPLACE_IND/OM_OBJECT_UPDATE_IND, it
|
||
// must confirm the relevant operation by calling OM_ObjectReplaceConfirm or
|
||
// OM_ObjectUpdateConfirm.
|
||
//
|
||
// When the functions are invoked, ObMan replaces/updates the object
|
||
// specified by <hWSGroup>, <worksetID> and <pObj>. It is bad Groupware
|
||
// programming practice for a Client to unduly delay invoking this function.
|
||
//
|
||
// Note however that these functions have a purely local effect: delaying
|
||
// (or executing) replace/update confirms at one node will not affect the
|
||
// contents of the workset group at any other node.
|
||
//
|
||
// Any pointer to the previous version of this object which the Client had
|
||
// obtained using OM_ObjectRead becomes invalid and should not be referred
|
||
// to again (i.e. the functions perform an implicit OM_ObjectRelease).
|
||
//
|
||
// The functions will cause an assertion failure if ObMan is not expecting a
|
||
// replace- or update-confirmation for this object.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// When the primary Client of a workset group confirms an update or replace
|
||
// using this function, an OM_OBJECT_UPDATED_IND/OM_OBJECT_REPLACED_IND is
|
||
// posted to all local secondary Clients of the workset group.
|
||
//
|
||
// Return Codes
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
|
||
UINT OM_ObjectLockReq(POM_CLIENT pomClient, OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID, POM_OBJECT pObj, BOOL reserved,
|
||
OM_CORRELATOR * pCorrelator);
|
||
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This is an asynchronous function which requests a lock for the object
|
||
// specified by <pObj> in the workset identified by <worksetID> and
|
||
// <hWSGroup>. When ObMan has processed the lock request, it will send an
|
||
// OM_OBJECT_LOCK_CON to the Client indicating success or the reason for
|
||
// failure.
|
||
//
|
||
// ------------------------------------------------------------------------
|
||
//
|
||
// Note: OM_ObjectLockReq and OM_ObjectUnlock are not implemented in
|
||
// DC-Groupware R1.1.
|
||
//
|
||
// ------------------------------------------------------------------------
|
||
//
|
||
// Holding an object lock prevents other Clients from
|
||
//
|
||
// - locking the workset
|
||
//
|
||
// - locking the object
|
||
//
|
||
// - updating or replacing the object
|
||
//
|
||
// - deleting the object.
|
||
//
|
||
// It does not prevent other Clients from reading the object or moving it
|
||
// within a workset.
|
||
//
|
||
// The function will cause an assertion failure if the Client requesting the
|
||
// lock already holds or has requested a lock which is equal to or after
|
||
// this one in the Universal Locking Order.
|
||
//
|
||
// On successful completion of the function, the value at <pCorrelator> is a
|
||
// value which the Client can use to correlate the subsequent
|
||
// OM_OBJECT_LOCK_CON event with this request.
|
||
//
|
||
// The <reserved> parameter is not used in DC-Groupware R1.1 and must be set
|
||
// to zero.
|
||
//
|
||
// A Client must release the lock when it no longer needs it, using the
|
||
// OM_ObjectUnlock function. Locks will be automatically released when a
|
||
// Client closes the workset or deregisters from the workset group.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// Invoking this function will cause the OM_OBJECT_LOCK_CON event to be
|
||
// posted to the invoking Client at some later time.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
//
|
||
//
|
||
|
||
void OM_ObjectUnlock(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function unlocks the object specified by <worksetID> and <pObj>.
|
||
// This must be the lock most recently acquired or requested by the Client;
|
||
// otherwise, the lock violation error causes an assertion failure.
|
||
//
|
||
// If this function is called before the OM_OBJECT_LOCK_CON event is
|
||
// received, the Client will not subsequently receive the event.
|
||
//
|
||
// ------------------------------------------------------------------------
|
||
//
|
||
// Note: OM_ObjectLockReq and OM_ObjectUnlock are not implemented in
|
||
// DC-Groupware R1.1.
|
||
//
|
||
// ------------------------------------------------------------------------
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// This function causes an OM_OBJECT_UNLOCK_IND to be posted to all other
|
||
// Clients which have the workset open.
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
UINT OM_ObjectH(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObjOther,
|
||
POM_OBJECT * pObj,
|
||
OM_POSITION omPos);
|
||
|
||
UINT OM_ObjectRead(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj,
|
||
POM_OBJECTDATA * ppData);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function enables a Client to read the contents of an object by
|
||
// converting an object handle into a pointer to the object.
|
||
//
|
||
// On successful completion, the value at <ppObject> points to the specified
|
||
// object.
|
||
//
|
||
// Invoking this function causes the object to be held in memory at the
|
||
// location indicated by the return value at <ppObject>. When it has
|
||
// finished reading the object, the Client must release it using the
|
||
// OM_ObjectRelease function. Holding object pointer for extended lengths
|
||
// of time may adversely affect ObMan's ability to efficiently manage its
|
||
// memory.
|
||
//
|
||
// This pointer is valid until the Client releases the object, either
|
||
// explicitly with OM_ObjectRelease or implicitly.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
//
|
||
//
|
||
|
||
void OM_ObjectRelease(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj,
|
||
POM_OBJECTDATA * ppData);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// Calling this function indicates to ObMan that the Client has finished
|
||
// reading the object specified by the handle <pObj>. The <ppObject>
|
||
// parameter is a pointer to a pointer to the object, which was previously
|
||
// obtained using OM_ObjectRead.
|
||
//
|
||
// On successful completion, the pointer to this object which the Client
|
||
// acquired using OM_ObjectRead becomes invalid (as the object may
|
||
// subsequently move in memory) and the value at <ppObject> is set to NULL
|
||
// to prevent the Client from using it again.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
UINT OM_ObjectAlloc(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
UINT length,
|
||
POM_OBJECTDATA * ppData);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function allocates a new, empty object the <data> field of which is
|
||
// <length> bytes long. The object must be intended for subsequent
|
||
// insertion into the workset specified by <hWSGroup> and <worksetID>.
|
||
//
|
||
// Note that the <length> parameter is the length of the object's data field
|
||
// (so the total memory requirement for this function is length+4 bytes).
|
||
//
|
||
// The contents of the memory allocated are undefined, and it is the
|
||
// Client's responsibility to fill in the <length> field at the start of the
|
||
// object.
|
||
//
|
||
// On successful completion, the value at <ppObject> points to the new
|
||
// object. This pointer is valid until the Client returns the object to
|
||
// ObMan using one of the functions mentioned here.
|
||
//
|
||
// A Client may write in this object and will normally insert it in the
|
||
// workset for which it was allocated using one of the object add, update or
|
||
// replace functions. However, if a Client fails to do so or decides for
|
||
// some other reason not to do so, it must free up the object by calling the
|
||
// OM_ObjectDiscard function.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
//
|
||
//
|
||
|
||
void OM_ObjectDiscard(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECTDATA * ppData);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This function discards an object which a Client previously allocated
|
||
// using OM_ObjectAlloc. A Client will call this function if for some
|
||
// reason it does not want to or cannot insert the object into the workset
|
||
// for which it was allocated. A Client must not call this function for an
|
||
// object which it has already added to a workset or used to update or
|
||
// replace an object in a workset.
|
||
//
|
||
// On successful completion, the value at <ppObject> is set to NULL to
|
||
// prevent the Client from accessing the object again.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
UINT OM_ObjectIDToPtr(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
OM_OBJECT_ID objectID,
|
||
POM_OBJECT * ppObj);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This functions converts an object ID to an object handle. If no object
|
||
// with the specified ID is found in the specified workset, an error is
|
||
// returned.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// OM_RC_BAD_OBJECT_ID
|
||
//
|
||
//
|
||
|
||
void OM_ObjectPtrToID(POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_OBJECT pObj,
|
||
POM_OBJECT_ID pObjectID);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This functions converts an object handle to an object ID.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// None
|
||
//
|
||
//
|
||
|
||
|
||
|
||
//
|
||
//
|
||
// Description
|
||
//
|
||
// These functions return information about a particular primary Client
|
||
// (identified by <hPerson>) of the workset group identified by <hWSGroup>
|
||
// <function profile> combination.
|
||
//
|
||
// If the person handle <hPerson> is invalid, the OM_RC_NO_SUCH_PERSON error
|
||
// is returned.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// OM_RC_NO_SUCH_PERSON
|
||
// Utility Service return codes
|
||
//
|
||
//
|
||
|
||
UINT OM_GetNetworkUserID(
|
||
POM_CLIENT pomClient,
|
||
OM_WSGROUP_HANDLE hWSGroup,
|
||
NET_UID * pNetUserID);
|
||
|
||
//
|
||
//
|
||
// Description:
|
||
//
|
||
// This functions returns ObMan's Network user ID for the call which
|
||
// contains the workset group specified by <hWSGroup>.
|
||
//
|
||
// This network ID corresponds to the <creator> field of objects defined by
|
||
// the Object Manager Function Profile.
|
||
//
|
||
// If the specified workset group is a local workset group (i.e. its
|
||
// "call" is OM_NO_CALL), then the function returns OM_RC_LOCAL_WSGROUP.
|
||
//
|
||
// Ensuing Events:
|
||
//
|
||
// None
|
||
//
|
||
// Return Codes:
|
||
//
|
||
// 0 (== OK)
|
||
// OM_RC_LOCAL_WSGROUP
|
||
//
|
||
//
|
||
|
||
|
||
BOOL CALLBACK OMSEventHandler(LPVOID pomClient, UINT event, UINT_PTR param1, UINT_PTR param2);
|
||
|
||
//
|
||
//
|
||
// Description
|
||
//
|
||
// This is the handler that ObMan registers (as a Utility Service event
|
||
// handler) for Client tasks to trap ObMan events. It serves two main
|
||
// purposes:
|
||
//
|
||
// - some state changes associated with events posted to Client tasks
|
||
// are better made when the event arrives than when it is posted
|
||
//
|
||
// - this handler can detect and discard "out-of-date" events, such as
|
||
// those arriving for a workset which a Client has just closed.
|
||
//
|
||
// The first parameter is the Client's ObMan handle, as returned by
|
||
// OM_Register, cast to a UINT.
|
||
//
|
||
// The second parameter is the event to be processed.
|
||
//
|
||
// The third and fourth parameters to the function are the two parameters
|
||
// associated with the event.
|
||
//
|
||
//
|
||
|
||
|
||
//
|
||
//
|
||
// OM_OUT_OF_RESOURCES_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This abnormal failure event is posted when ObMan cannot allocate
|
||
// sufficient resources to complete a particular action, usually one
|
||
// prompted by a network event.
|
||
//
|
||
// Clients should treat this event as a fatal error and attempt to
|
||
// terminate.
|
||
//
|
||
// The parameters included with the event are reserved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_WSGROUP_REGISTER_CON
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted when ObMan has finished processing a request to
|
||
// register a Client with a workset group. The parameters included with
|
||
// the event are defined as follows:
|
||
//
|
||
// - the second parameter is an OM_EVENT_DATA32 structure:
|
||
//
|
||
// - the <correlator> field is the value which was returned by
|
||
// the corresponding invocation of the OM_WSGroupRegisterPReq
|
||
// function
|
||
//
|
||
// - the <result> field is one of
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_OUT_OF_RESOURCES
|
||
// OM_RC_TOO_MANY_CLIENTS
|
||
// OM_RC_TOO_MANY_WSGROUPS
|
||
// OM_RC_ALREADY_REGISTERED
|
||
// OM_RC_CANNOT_CREATE_WSG
|
||
//
|
||
// - if the <result> field is 0 (== OK), the first parameter is an
|
||
// OM_EVENT_DATA16 structure which contains a newly created handle
|
||
// to the workset group involved (the <worksetID> field is
|
||
// reserved).
|
||
//
|
||
// Once a Client has received this notification, it will receive
|
||
// OM_WORKSET_NEW_IND events to notify it of the existing worksets in the
|
||
// group, if there are any.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_WSGROUP_MOVE_CON
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted when ObMan has finished processing a request to
|
||
// move an existing workset group into a Call. The parameters included
|
||
// with the event are defined as follows:
|
||
//
|
||
// - the second parameter is an OM_EVENT_DATA32 structure:
|
||
//
|
||
// - the <correlator> field is the value which was returned by
|
||
// the corresponding invocation of the OM_WSGroupMoveReq
|
||
// function
|
||
//
|
||
// - the <result> field is one of
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_CANNOT_MOVE_WSGROUP
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 structure which contains the
|
||
// handle of the workset group involved (the <worksetID> field is
|
||
// reserved).
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_WSGROUP_MOVE_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted when ObMan has moved a workset group either into or
|
||
// out of a Call.
|
||
//
|
||
// This will happen
|
||
//
|
||
// - when the workset group is moved out of a Call (because e.g. the call
|
||
// has ended), thus becoming a local workset group
|
||
//
|
||
// - when a local Client requests to move a local workset group into a
|
||
// Call.
|
||
//
|
||
// The parameters included with the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset group involved (the <worksetID> field is reserved).
|
||
//
|
||
// - the second parameter is the handle of the Call into which the
|
||
// workset group has been moved (== OM_NO_CALL when the workset group
|
||
// has been moved out of a Call).
|
||
//
|
||
// If the workset group has been moved out of a call, it continues in
|
||
// existence as a local workset group and the Client may continue to use it
|
||
// as before. However, no updates will be sent to or received from Clients
|
||
// residing on other nodes.
|
||
//
|
||
// If a Client wishes to move this workset group into another Call, it can
|
||
// do so using the OM_WSGroupMoveReq function. Note that an attempt to move
|
||
// the workset group back into the same Call is likely to fail due to a name
|
||
// clash since the original version probably still exists in the Call.
|
||
//
|
||
// This event may also be prompted by the failure to allocate memory for a
|
||
// large object being transferred from another node.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_WORKSET_NEW_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted when a new workset has been created (by the
|
||
// receiving Client or by another Client). The parameters included with
|
||
// the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset involved
|
||
//
|
||
// - the second parameter is reserved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_WORKSET_OPEN_CON
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted when ObMan has finished processing a request to
|
||
// open a workset for a specific Client.
|
||
//
|
||
// The parameters included with the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset involved
|
||
//
|
||
// - the second parameter is a OM_EVENT_DATA32 structure:
|
||
//
|
||
// - the <correlator> field is the correlator which was
|
||
// returned by the corresponding invocation of the
|
||
// OM_WorksetOpenReq function
|
||
//
|
||
// - the <result> field is one of
|
||
//
|
||
// 0 (== OK)
|
||
// OM_RC_OUT_OF_RESOURCES.
|
||
//
|
||
// In all but the case of OK, the open request has failed and the Client
|
||
// does not have the workset open.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_WORKSET_LOCK_CON
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted to a Client when ObMan has succeeded in obtaining,
|
||
// or failed to obtain, a workset lock which the Client had requested. The
|
||
// parameters included with the event are as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset involved
|
||
//
|
||
// - the second parameter is a OM_EVENT_DATA32 structure:
|
||
//
|
||
// - the <correlator> field is the correlator which was
|
||
// returned by the corresponding invocation of the
|
||
// OM_WorksetLockReq function
|
||
//
|
||
// - the <result> field is one of
|
||
//
|
||
// 0 (== OK)
|
||
// OM_RC_OUT_OF_RESOURCES
|
||
// OM_RC_WORKSET_LOCKED
|
||
// OM_RC_OBJECT_LOCKED.
|
||
//
|
||
// In all but the case of OK, the lock request has failed and the Client
|
||
// does not hold the lock.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_WORKSET_UNLOCK_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted when a workset is unlocked using the
|
||
// OM_WorksetUnlock function. The parameters included with the event are
|
||
// as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset involved
|
||
//
|
||
// - the second parameter is reserved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_WORKSET_CLEAR_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted (to primary Clients only) after a local or remote
|
||
// Client has invoked the OM_WorksetClear function. After a Client receives
|
||
// this event, it must call OM_WorksetClearConfirm to enable ObMan to clear
|
||
// the workset.
|
||
//
|
||
// The parameters included with the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset involved
|
||
//
|
||
// - the second parameter is reserved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_WORKSET_CLEARED_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted (to secondary Clients only) when a workset has been cleared.
|
||
//
|
||
// The parameters included with the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset involved
|
||
//
|
||
// - the second parameter is reserved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_OBJECT_ADD_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted after a new object has been added to a workset.
|
||
//
|
||
// The parameters to the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset group and workset involved
|
||
//
|
||
// - the second parameter is the handle of the object involved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_OBJECT_MOVE_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted after a new object has been moved within a workset.
|
||
//
|
||
// The parameters to the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset group and workset involved
|
||
//
|
||
// - the second parameter is the handle of the object involved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_OBJECT_DELETE_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted (to primary Clients only) after a local or remote
|
||
// Client has invoked the OM_ObjectDelete function. After a Client
|
||
// receives this event, it must call OM_ObjectDeleteConfirm to enable ObMan
|
||
// to delete the object.
|
||
//
|
||
// The parameters to the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset group and workset involved
|
||
//
|
||
// - the second parameter is the handle of the object involved.
|
||
//
|
||
// See also OM_OBJECT_DELETED_IND.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_OBJECT_REPLACE_IND
|
||
// OM_OBJECT_UPDATE_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// These events are posted (to primary Clients only) after a local or remote
|
||
// Client has invoked the OM_ObjectReplace/OM_ObjectUpdate function. After
|
||
// a Client receives this event, it must call OM_ObjectReplaceConfirm/
|
||
// OM_ObjectUpdateConfirm to enable ObMan to replace/update the object.
|
||
//
|
||
// The parameters to the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset group and workset involved
|
||
//
|
||
// - the second parameter is the handle of the object involved.
|
||
//
|
||
// See also OM_OBJECT_REPLACED_IND/OM_OBJECT_UPDATED_IND.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_OBJECT_DELETED_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted (to secondary Clients only) when an object has been
|
||
// deleted from a workset. The handle it contains is thus invalid and can
|
||
// only be used to cross-reference against lists maintained by the Client.
|
||
//
|
||
// The Client must not invoke the OM_ObjectDeleteConfirm function on
|
||
// receipt of this event.
|
||
//
|
||
// The parameters to the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 identifying the workset
|
||
// group and workset involved
|
||
//
|
||
// - the second parameter is the handle of the object involved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_OBJECT_REPLACED_IND
|
||
// OM_OBJECT_UPDATED_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// These events are posted (to secondary Clients only) when an object has
|
||
// been replaced or updated. When the Client receives this event, the
|
||
// previous data is thus inaccessible.
|
||
//
|
||
// The Client must not invoke the OM_ObjectReplaceConfirm/
|
||
// OM_ObjectUpdateConfirm function on receipt of this event.
|
||
//
|
||
// The parameters to the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 identifying the workset
|
||
// group and workset involved
|
||
//
|
||
// - the second parameter is the handle of the object involved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_OBJECT_LOCK_CON
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted to a Client when ObMan has succeeded in obtaining
|
||
// (or failed to obtain) an object lock which the Client had requested.
|
||
// The parameters included with the event are defined as follows:
|
||
//
|
||
// - the first parameter is reserved
|
||
//
|
||
// - the second parameter is a OM_EVENT_DATA32 structure:
|
||
//
|
||
// - the <correlator> field is the correlator which was
|
||
// returned by the corresponding invocation of the
|
||
// OM_ObjectLockReq function
|
||
//
|
||
// - the <result> field is one of
|
||
//
|
||
// 0 (== OK)
|
||
// Utility Service return codes
|
||
// OM_RC_WORKSET_LOCKED
|
||
// OM_RC_OBJECT_LOCKED.
|
||
//
|
||
// In all but the case of OK, the lock request has failed and the Client
|
||
// does not hold the lock.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_OBJECT_UNLOCK_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// This event is posted when a Client has released an object lock using the
|
||
// OM_ObjectUnlock function.
|
||
//
|
||
// The parameters to the event are defined as follows:
|
||
//
|
||
// - the first parameter is a OM_EVENT_DATA16 which identifies the
|
||
// workset group and workset involved
|
||
//
|
||
// - the second parameter is the handle of the object involved.
|
||
//
|
||
//
|
||
|
||
//
|
||
//
|
||
// OM_PERSON_JOINED_IND
|
||
// OM_PERSON_LEFT_IND
|
||
// OM_PERSON_DATA_CHANGED_IND
|
||
//
|
||
// Description:
|
||
//
|
||
// These events inform clients registered with a workset group when clients
|
||
// register with the workset group, deregister from it and set their person
|
||
// data, respectively.
|
||
//
|
||
// A client will also receive the appropriate events when it performs these
|
||
// actions itself.
|
||
//
|
||
// Parameters:
|
||
//
|
||
// The first parameter in an OM_EVENT_DATA16 which identifies the workset
|
||
// group to which the event relates. The <worksetID> field of the structure
|
||
// is undefined.
|
||
//
|
||
// The second parameter is the POM_EXTOBJEECT for the person to which the
|
||
// event relates. These handles are not guaranteed to be still valid. In
|
||
// particular, the handle received on the OM_PERSON_LEFT_IND is never valid.
|
||
// If a client wishes to correlate these events with a list of clients,
|
||
// then it is responsible for maintaining the list itself.
|
||
//
|
||
//
|
||
|
||
|
||
//
|
||
// OMP_Init()
|
||
// OMP_Term()
|
||
//
|
||
|
||
BOOL OMP_Init(BOOL * pfCleanup);
|
||
void OMP_Term(void);
|
||
|
||
|
||
void CALLBACK OMPExitProc(LPVOID pomPrimary);
|
||
BOOL CALLBACK OMPEventsHandler(LPVOID pomPrimary, UINT event, UINT_PTR param1, UINT_PTR param2);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessNetData(...)
|
||
//
|
||
// This function is called when a NET_EV_SEND_INDICATION event is received,
|
||
// indicating the arrival of a message from another instance of ObMan. The
|
||
// function determines which OMNET_... message is contained in the network
|
||
// packet and invokes the appropriate ObMan function to process the
|
||
// message.
|
||
//
|
||
//
|
||
|
||
void ProcessNetData(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
PNET_SEND_IND_EVENT pNetEvent);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessNetDetachUser(...)
|
||
//
|
||
// This function is called when a NET_EV_DETACH_INDICATION event is received
|
||
// from the network layer.
|
||
//
|
||
// The function determines whether
|
||
//
|
||
// - we have been thrown out of the Domain by MCS, or
|
||
//
|
||
// - someone else has left/been thrown out
|
||
//
|
||
// and calls ProcessOwnDetach or ProcessOtherDetach as appropriate.
|
||
//
|
||
//
|
||
|
||
void ProcessNetDetachUser(POM_PRIMARY pomPrimary, POM_DOMAIN pDomain,
|
||
NET_UID userID);
|
||
|
||
//
|
||
//
|
||
// ProcessNetAttachUser(...)
|
||
//
|
||
// This function is called when a NET_ATTACH_INDICATION event is received
|
||
// from the network layer. The function calls MG_ChannelJoin to join us
|
||
// to our own single-user channel.
|
||
//
|
||
//
|
||
|
||
void ProcessNetAttachUser(POM_PRIMARY pomPrimary, POM_DOMAIN pDomain,
|
||
NET_UID userID, NET_RESULT result);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessNetJoinChannel(...)
|
||
//
|
||
// This function is called when a NET_EV_JOIN_CONFIRM event is received from
|
||
// the network layer. This function determines whether the join was
|
||
// successful and whether the channel joined is
|
||
//
|
||
// - our own single-user channel
|
||
//
|
||
// - the well-known ObManControl channel
|
||
//
|
||
// - a regular workset group channel
|
||
//
|
||
// and then takes appropriate action.
|
||
//
|
||
//
|
||
|
||
void ProcessNetJoinChannel(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
PNET_JOIN_CNF_EVENT pNetJoinCnf);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessNetLeaveChannel(...)
|
||
//
|
||
// This function is called when a NET_EV_LEAVE_INDICATION event is received
|
||
// from the network layer, indicating that we've been thrown out of a
|
||
// channel. This function determines whether the channel is
|
||
//
|
||
// - our own single-user channel
|
||
//
|
||
// - the well-known ObManControl channel
|
||
//
|
||
// - a regular workset group channel
|
||
//
|
||
// and then takes appropriate action; in the first two cases, this means
|
||
// behaving as if we've been thrown out of the Domain altogether, whereas
|
||
// we treat the last case just as if a Client had asked to move the workset
|
||
// group into the local Domain.
|
||
//
|
||
//
|
||
|
||
UINT ProcessNetLeaveChannel(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
NET_CHANNEL_ID channel);
|
||
|
||
|
||
//
|
||
//
|
||
// DomainRecordFindOrCreate(...)
|
||
//
|
||
//
|
||
|
||
UINT DomainRecordFindOrCreate(POM_PRIMARY pomPrimary,
|
||
UINT callID,
|
||
POM_DOMAIN * ppDomain);
|
||
|
||
|
||
//
|
||
//
|
||
// DomainDetach(...)
|
||
//
|
||
void DomainDetach(POM_PRIMARY pomPrimary, POM_DOMAIN * ppDomain, BOOL fExit);
|
||
|
||
|
||
//
|
||
//
|
||
// DeregisterLocalClient(...)
|
||
//
|
||
// This function is called by the ObMan task after the local client
|
||
// deregisters from a workset group. It causes this node's person object
|
||
// for the workset group to be deleted.
|
||
//
|
||
// If this node was the last node to be registered with the workset group,
|
||
// it also causes the relevant INFO object to be discarded.
|
||
//
|
||
// If this in turn causes the last workset group in the domain (which must
|
||
// be ObManControl) to be removed, ObMan is detached from the domain and
|
||
// the domain record becomes invalid. In this case, the ppDomain
|
||
// pointer passed in is nulled out.
|
||
//
|
||
//
|
||
|
||
void DeregisterLocalClient(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN * ppDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
BOOL fExit);
|
||
|
||
|
||
//
|
||
//
|
||
// GetOMCWorksetPtr(...)
|
||
//
|
||
// This function derives a pointer to a specified workset in the
|
||
// ObManControl workset in the specified Domain.
|
||
//
|
||
//
|
||
|
||
UINT GetOMCWorksetPtr(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OM_WORKSET_ID worksetID,
|
||
POM_WORKSET * ppWorkset);
|
||
|
||
|
||
//
|
||
//
|
||
// SayWelcome(...)
|
||
//
|
||
// This function is called
|
||
//
|
||
// - when the "top" ObMan finishes initalizing (the WELCOME is broadcast)
|
||
//
|
||
// - when ObMan receives an HELLO message from a late joiner (the WELCOME
|
||
// is sent to the late joiner)
|
||
//
|
||
//
|
||
|
||
UINT SayWelcome(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
NET_CHANNEL_ID channel);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessWelcome(...)
|
||
//
|
||
// Called when a WELCOME is received from another node. This may be in
|
||
// response to a HELLO, or it may be the "top" ObMan announcing the
|
||
// completion of its initialization.
|
||
//
|
||
// If this is the first WELCOME we've got for this Domain, we merge the
|
||
// capabilities and reply to the sender, asking for a copy of the
|
||
// ObManControl workset group.
|
||
//
|
||
//
|
||
|
||
UINT ProcessWelcome(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POMNET_JOINER_PKT pWelcomePkt,
|
||
UINT lengthOfPkt);
|
||
|
||
|
||
//
|
||
//
|
||
// SayHello(...)
|
||
//
|
||
// Called when we join that domain and determine that we're not the "top"
|
||
// ObMan. We expect a WELCOME to come in response. We include our
|
||
// capabilities in the broadcast HELLO packet so that everyone knows what
|
||
// we support.
|
||
//
|
||
//
|
||
|
||
UINT SayHello(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessHello(...)
|
||
//
|
||
// Called when we get a HELLO from another node. If we've completed our
|
||
// own initialization in the domain, we merge in that node's capabilities,
|
||
// then we respond with a WELCOME.
|
||
//
|
||
//
|
||
|
||
UINT ProcessHello(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POMNET_JOINER_PKT pHelloPkt,
|
||
UINT lengthOfPkt);
|
||
|
||
|
||
//
|
||
//
|
||
// MergeCaps(...)
|
||
//
|
||
// Called by ProcessHello and ProcessWelcome to merge in capabilities
|
||
// received in the packet (which will be, respectively, a late joiner's
|
||
// capabilities or the domain-wide capabilities as determined by the sender
|
||
// of the WELCOME).
|
||
//
|
||
//
|
||
|
||
void MergeCaps(POM_DOMAIN pDomain,
|
||
POMNET_JOINER_PKT pJoinerPkt,
|
||
UINT lengthOfPkt);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessOwnDetach(...)
|
||
//
|
||
// This function is called when a NET_EV_DETACH_INDICATION is received for a
|
||
// user ID that matches our own. The function moves all of the workset
|
||
// groups for this Domain into ObMan's own "local" Domain.
|
||
//
|
||
//
|
||
UINT ProcessOwnDetach(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessOtherDetach(...)
|
||
//
|
||
// This function is called when a NET_EV_DETACH_INDICATION is received for a
|
||
// user ID that doesn't match our own. The function examines each workset
|
||
// in the ObManControl workset group and deletes any registration objects
|
||
// that the departed node may have put there.
|
||
//
|
||
// If any local Clients have any of these worksets open, they are informed
|
||
// of the delete. However, OBEJCT_DELETE messages are not broadcast
|
||
// throughout the Domain, since each ObMan will do them locally.
|
||
//
|
||
//
|
||
|
||
UINT ProcessOtherDetach(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
NET_UID detachedUserID);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGRegisterStage1(...)
|
||
//
|
||
// This function is ObMan's handler for the OMINT_EVENT_WSGROUP_REGISTER
|
||
// function. It is the first step in the chain of functions running in the
|
||
// ObMan context which are invoked during the workset group registration
|
||
// process (the OM_WSGroupRegisterReq, running in the Client context,
|
||
// posted the original OMINT_EVENT_WSGROUP_REGISTER event).
|
||
//
|
||
// This function ensures that we are fully attached to the Domain (if not,
|
||
// it starts the Domain attach procedure and reposts a delayed
|
||
// OMINT_EVENT_WSGROUP_REGISTER event) and then starts the process of locking
|
||
// workset #0 in the ObManControl workset group.
|
||
//
|
||
//
|
||
|
||
void WSGRegisterStage1(POM_PRIMARY pomPrimary,
|
||
POM_WSGROUP_REG_CB pRegistrationCB);
|
||
|
||
|
||
//
|
||
// ProcessOMCLockConfirm(...)
|
||
//
|
||
void ProcessOMCLockConfirm(POM_PRIMARY pomPrimary, OM_CORRELATOR cor, UINT result);
|
||
|
||
|
||
//
|
||
// ProcessCheckpoint(...)
|
||
//
|
||
void ProcessCheckpoint(POM_PRIMARY pomPrimary, OM_CORRELATOR cor, UINT result);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGRegisterStage2(...)
|
||
//
|
||
// This function is called when we have successfully locked workset #0 in
|
||
// ObManControl.
|
||
//
|
||
// The function checks workset #0 in ObManControl to see if the workset
|
||
// group we're trying to register the Client with already exists in the
|
||
// Domain.
|
||
//
|
||
// If it does, it finds the channel number and requests to join the
|
||
// channel.
|
||
//
|
||
// If it doesn't, it requests to join a new channel and also calls
|
||
// WSGGetNewID to generate a new workset group ID (unique within the
|
||
// Domain).
|
||
//
|
||
//
|
||
|
||
void WSGRegisterStage2(POM_PRIMARY pomPrimary,
|
||
POM_WSGROUP_REG_CB pRegistrationCB);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGGetNewID(...)
|
||
//
|
||
// This function is called by WSGRegisterStage2 to generate a new workset
|
||
// group ID, in the case where the workset group doesn't already exist.
|
||
//
|
||
// It also creates a new workset in ObManControl with the same ID as the ID
|
||
// just generated. This workset which will hold the registration objects
|
||
// for the new workset group
|
||
//
|
||
//
|
||
|
||
UINT WSGGetNewID(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP_ID pWSGroupID);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGRegisterStage3(...)
|
||
//
|
||
// This function is called by ProcessNetJoinChannel when a Join event
|
||
// arrives for a workset group channel.
|
||
//
|
||
// Depending on whether or not the workset was created in Stage2, the
|
||
// function calls WSGAnnounce (if it was) or WSGCatchUp (if it was not).
|
||
//
|
||
// It then unlocks the ObManControl workset and calls WSGRegisterResult.
|
||
//
|
||
//
|
||
|
||
void WSGRegisterStage3(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP_REG_CB pRegistrationCB,
|
||
NET_CHANNEL_ID channelID);
|
||
|
||
|
||
//
|
||
//
|
||
// CreateAnnounce(...)
|
||
//
|
||
// This function is called by WSGRegisterStage3 after we have joined the
|
||
// channel for a new workset group.
|
||
//
|
||
// The function announces the new workset group throughout the Domain by
|
||
// adding an object containing the name, Function Profile, ObMan ID and MCS
|
||
// channel of the workset group to workset #0 in ObManControl.
|
||
//
|
||
// Note that this "announcement" cannot be made before the Join completes
|
||
// since we only learn the ID of the channel joined when we receive the
|
||
// Join event.
|
||
//
|
||
//
|
||
|
||
UINT CreateAnnounce(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// RegAnnounceBegin(...)
|
||
//
|
||
// This function adds a registration object to a workset in ObManControl.
|
||
// The workset is determined by the ID of the workset group identified by
|
||
// <pWSGroup>.
|
||
//
|
||
// This function is called
|
||
//
|
||
// - when ObMan creates a workset group
|
||
//
|
||
// - when ObMan receives a request to send a workset group to a late
|
||
// joiner.
|
||
//
|
||
// In the first case, the registration object identifies this node's use of
|
||
// the workset group. In the second case, the reg object identifies the
|
||
// late joiner's use of the workset group.
|
||
//
|
||
// The object ID returned is the ID of the reg object added.
|
||
//
|
||
//
|
||
|
||
UINT RegAnnounceBegin(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
NET_UID nodeID,
|
||
POM_OBJECT * ppObjReg);
|
||
|
||
|
||
//
|
||
//
|
||
// RegAnnounceComplete(...)
|
||
//
|
||
// This function is called when we are fully caught up with a workset group
|
||
// we have joined, either because we have received the SEND_COMPLETE
|
||
// message or because we just created the group ourselves.
|
||
//
|
||
// The function updates the reg object specified by <regObjectID> by
|
||
// changing the <status> field to READY_TO_SEND.
|
||
//
|
||
//
|
||
|
||
UINT RegAnnounceComplete(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGCatchUp(...)
|
||
//
|
||
// This function is called by Stage3 after we have joined the channel
|
||
// belonging to a workset group which already exists in the Domain.
|
||
//
|
||
// The function examines ObManControl to find the MCS ID of an instance of
|
||
// ObMan which claims to have a copy of this workset group, then sends it a
|
||
// request to transfer the workset group.
|
||
//
|
||
// The function also posts a delayed timeout event so we don't wait for
|
||
// ever to get a workset group from a particular node (this timeout is
|
||
// processed in ProcessWSGSendTimeout).
|
||
//
|
||
//
|
||
|
||
UINT WSGCatchUp(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGRegisterResult(...)
|
||
//
|
||
// This function is called wherever any of the workset group registration
|
||
// functions have done enough processing to know the outcome of the
|
||
// registration attempt. If all is well, it will be called by Stage3 but
|
||
// it may also be called earlier if an error occurs.
|
||
//
|
||
// The function posts an OM_WSGROUP_REGISTER_CON event to the Clientn which
|
||
// initiated the workset group registration.
|
||
//
|
||
//
|
||
|
||
void WSGRegisterResult(POM_PRIMARY pomPrimary,
|
||
POM_WSGROUP_REG_CB pRegistrationCB,
|
||
UINT result);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGRegisterRetry(...)
|
||
//
|
||
// This function is called wherever any of the workset group registration
|
||
// functions encounter a recoverable "error" situation, such as failing to
|
||
// get the ObManControl lock.
|
||
//
|
||
// This function checks if we've exceeded the retry count for this
|
||
// registration attempt and if not, reposts the OMINT_EVENT_WSGROUP_REGISTER
|
||
// event, so that the whole process is started again from Stage1.
|
||
//
|
||
// If we've run out of retries, WSGRegisterResult is invoked to post
|
||
// failure to the Client.
|
||
//
|
||
//
|
||
|
||
void WSGRegisterRetry(POM_PRIMARY pomPrimary,
|
||
POM_WSGROUP_REG_CB pRegistrationCB);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessSendReq(...)
|
||
//
|
||
// This function is called when an OMNET_WSGROUP_SEND_REQ message is
|
||
// received from another node (i.e. a late joiner)
|
||
//
|
||
// The function starts the process of sending the workset group contents to
|
||
// the late joiner.
|
||
//
|
||
//
|
||
void ProcessSendReq(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POMNET_WSGROUP_SEND_PKT pSendReq);
|
||
|
||
|
||
//
|
||
//
|
||
// SendWSGToLateJoiner(...)
|
||
//
|
||
// This function is called when the checkpointing for a workset has
|
||
// completed. It sends the contents to the late joiner node.
|
||
//
|
||
//
|
||
|
||
void SendWSGToLateJoiner(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
NET_UID lateJoiner,
|
||
OM_CORRELATOR remoteCorrelator);
|
||
|
||
//
|
||
//
|
||
// ProcessSendMidway(...)
|
||
//
|
||
// This function is called when an OMNET_WSGROUP_SEND_MIDWAY message is
|
||
// received from another node (the node which was helping us by sending us
|
||
// the contents of a workset group).
|
||
//
|
||
// We have now received all the WORKSET_CATCHUP messages (one for each
|
||
// workset). If all is well we inform the client that registration has
|
||
// been successful and set the workset group state to
|
||
// PENDING_SEND_COMPLETE.
|
||
//
|
||
//
|
||
|
||
void ProcessSendMidway(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POMNET_WSGROUP_SEND_PKT pSendMidwayPkt);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessSendComplete(...)
|
||
//
|
||
// This function is called when an OMNET_WSGROUP_SEND_COMPLETE message is
|
||
// received from another node (the node which was helping us by sending us
|
||
// the contents of a workset group).
|
||
//
|
||
// If this message relates to the ObManControl workset group, we now have
|
||
// most of the ObManControl workset group (only "most" since there could be
|
||
// some recent objects still flying around).
|
||
//
|
||
// However, we do know that we have ALL the contents of workset #0 in
|
||
// ObManControl, since that workset is only ever altered under lock.
|
||
//
|
||
// Accordingly, we now consider ourselves to be fully-fledged members of
|
||
// the Domain, in the sense that we can correctly process our Clients
|
||
// requests to register with workset groups.
|
||
//
|
||
// If the message relates to another workset group, we now have enough of
|
||
// its contents to consider ourselves eligible to help other late joiners
|
||
// (as we have just been). Therefore, we announce this eligibilty
|
||
// throughout the Domain (using the ObManControl workset group).
|
||
//
|
||
//
|
||
|
||
UINT ProcessSendComplete(
|
||
POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POMNET_WSGROUP_SEND_PKT pSendCompletePkt);
|
||
|
||
|
||
//
|
||
//
|
||
// MaybeRetryCatchUp(...)
|
||
//
|
||
// This function is called on receipt of a DETACH indication from MCS or a
|
||
// SEND_DENY message from another node. In both cases we compare the
|
||
// helperNode field in OM_WSGROUP structure with the userID and if they
|
||
// match then we retry the catch up.
|
||
//
|
||
// Depending on the workset group status we do the following:
|
||
//
|
||
// PENDING_SEND_MIDWAY : Retry the registration from the top.
|
||
// PENDING_SEND_COMPLETE : Just repeat the catch up.
|
||
//
|
||
// If there is no one to catch up from then we do the following depending
|
||
// on the workset group status:
|
||
//
|
||
// PENDING_SEND_MIDWAY : Retry the registration from the top. Regardless
|
||
// of whether someone else is out there or not (they cannot be in the
|
||
// READY_TO_SEND state) we will end up in a consistent state.
|
||
//
|
||
// PENDING_SEND_COMPLETE : If two (or more) nodes are in this state and
|
||
// catching up from the same box who then leaves, they will have two
|
||
// partial sets of objects one of which may or may not be a subset of the
|
||
// other. If there is no one else in the READY_TO_SEND state then each
|
||
// node needs to obtain a copy of all the objects in a given workset at the
|
||
// other node.
|
||
//
|
||
//
|
||
|
||
void MaybeRetryCatchUp(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID,
|
||
NET_UID userID);
|
||
|
||
|
||
//
|
||
//
|
||
// IssueSendDeny(...)
|
||
//
|
||
// This function issues a SEND_DENY message to a remote node.
|
||
//
|
||
//
|
||
void IssueSendDeny(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID,
|
||
NET_UID sender,
|
||
OM_CORRELATOR remoteCorrelator);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGRecordMove(...)
|
||
//
|
||
// This function moves the record for specified workset group from one
|
||
// Domain record to another, and posts events to all relevant Clients. If
|
||
// does not check for name contention in the destination Domain.
|
||
//
|
||
//
|
||
|
||
void WSGRecordMove(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDestDomainRec,
|
||
POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGMove(...)
|
||
//
|
||
// This function moves the record for specified workset group from one
|
||
// Domain record to another, and posts events to all relevant Clients. If
|
||
// does not check for name contention in the destination Domain.
|
||
//
|
||
//
|
||
|
||
UINT WSGMove(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDestDomainRec,
|
||
POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// DomainAttach(...)
|
||
//
|
||
// This function calls MG_AttachUser to start the process of attaching to
|
||
// a Domain. It also allocates and initialises the local structures
|
||
// associated with the Domain (the Domain record).
|
||
//
|
||
// A pointer to the newly-created Domain record is returned.
|
||
//
|
||
//
|
||
|
||
UINT DomainAttach(POM_PRIMARY pomPrimary,
|
||
UINT callID,
|
||
POM_DOMAIN * ppDomainord);
|
||
|
||
|
||
//
|
||
//
|
||
// WSGRecordFindOrCreate(...)
|
||
//
|
||
// This function searches the workset group list in the specified Domain
|
||
// record for a workset group record whose name and FP match the ones
|
||
// specified. If none is found, a new workset group record is allocated,
|
||
// initialised and inserted into the list.
|
||
//
|
||
// A pointer to the found-or-created workset group record is returned.
|
||
//
|
||
// NOTE: This function does not cause ObMan to join the workset group
|
||
// channel or copy the workset group from another node if it
|
||
// exists elsewhere; it merely creates the local structures for
|
||
// the workset group.
|
||
//
|
||
//
|
||
|
||
UINT WSGRecordFindOrCreate(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OMWSG wsg,
|
||
OMFP fpHandler,
|
||
POM_WSGROUP * ppWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// ProcessSendQueue(...)
|
||
//
|
||
// This function prompts ObMan to examine the send queues for the specified
|
||
// Domain. If there are any messages queued for sending (including remains
|
||
// of messages which have been partly sent), ObMan will try to send more
|
||
// data. ObMan stops when either the send queues are all empty or the
|
||
// network layer has stopped giving us memory.
|
||
//
|
||
// The <domainRecBumped> flag indicates whether the Domain record has had
|
||
// its use count bumped; if TRUE, then this function calls UT_SubFreeShared
|
||
// to decrement the use count.
|
||
//
|
||
//
|
||
|
||
void ProcessSendQueue(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
BOOL domainRecBumped);
|
||
|
||
|
||
|
||
//
|
||
// ProcessWSGDiscard(...)
|
||
//
|
||
void ProcessWSGDiscard(POM_PRIMARY pomPrimary, POM_WSGROUP pWSGroup);
|
||
|
||
|
||
//
|
||
// ProcessWSGMove(...)
|
||
//
|
||
UINT ProcessWSGMove(POM_PRIMARY pomPrimary, long moveCBOffset);
|
||
|
||
|
||
//
|
||
// ProcessNetTokenGrab(...)
|
||
//
|
||
UINT ProcessNetTokenGrab(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
NET_RESULT result);
|
||
|
||
|
||
//
|
||
// ProcessCMSTokenAssign(...)
|
||
//
|
||
void ProcessCMSTokenAssign(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
BOOL success,
|
||
NET_TOKEN_ID tokenID);
|
||
|
||
|
||
//
|
||
// ProcessNetTokenInhibit(...)
|
||
//
|
||
UINT ProcessNetTokenInhibit(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
NET_RESULT result);
|
||
|
||
//
|
||
// CreateObManControl(...)
|
||
//
|
||
UINT ObManControlInit(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain);
|
||
|
||
|
||
//
|
||
// WSGDiscard(...)
|
||
//
|
||
void WSGDiscard(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
BOOL fExit);
|
||
|
||
|
||
//
|
||
// IssueSendReq(...)
|
||
//
|
||
UINT IssueSendReq(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
NET_UID remoteNode);
|
||
|
||
|
||
//
|
||
// GenerateUnlockMessage(...)
|
||
//
|
||
UINT GenerateUnlockMessage(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OM_WSGROUP_ID wsGroupID,
|
||
OM_WORKSET_ID worksetID,
|
||
POMNET_LOCK_PKT * ppUnlockPkt);
|
||
|
||
|
||
//
|
||
// ProcessWSGRegister(...)
|
||
//
|
||
void ProcessWSGRegister(POM_PRIMARY pomPrimary, POM_WSGROUP_REG_CB pRegCB);
|
||
|
||
|
||
//
|
||
// LockObManControl(...)
|
||
//
|
||
void LockObManControl(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OM_CORRELATOR * pLockCorrelator);
|
||
|
||
|
||
//
|
||
//
|
||
// MaybeUnlockObManControl(...)
|
||
//
|
||
// If the LOCKED_OMC flag is set in the registration CB, then unlock the
|
||
// Obman Control workset and clear the LOCKED_OMC flag.
|
||
//
|
||
//
|
||
|
||
void MaybeUnlockObManControl(POM_PRIMARY pomPrimary,
|
||
POM_WSGROUP_REG_CB pRegistrationCB);
|
||
|
||
|
||
//
|
||
// WSGRecordCreate(...)
|
||
//
|
||
UINT WSGRecordCreate(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
OMWSG wsg,
|
||
OMFP fpHandler,
|
||
POM_WSGROUP * ppWSGroup);
|
||
|
||
|
||
//
|
||
//
|
||
// WorksetDiscard(...)
|
||
//
|
||
// This function is called by WSGDiscard to discard the individual worksets
|
||
// of a workset group when the last local Client deregisters. It discards
|
||
// the contents of the workset, frees the workset record itself and clears
|
||
// the worksets's entry in the workset group record.
|
||
//
|
||
// It is not called when a workset is closed, since closing a workset does
|
||
// not discard its contents.
|
||
//
|
||
//
|
||
|
||
void WorksetDiscard(POM_WSGROUP pWSGroup, POM_WORKSET * pWorkset, BOOL fExit);
|
||
|
||
|
||
//
|
||
// ProcessLockNotify(...)
|
||
//
|
||
void ProcessLockNotify(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
NET_UID owner);
|
||
|
||
|
||
//
|
||
// SendMessagePkt(...)
|
||
//
|
||
UINT SendMessagePkt(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_SEND_INST pSendInst);
|
||
|
||
|
||
//
|
||
// SendMoreData(...)
|
||
//
|
||
UINT SendMoreData(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_SEND_INST pSendInst);
|
||
|
||
|
||
//
|
||
// StartReceive(...)
|
||
//
|
||
UINT StartReceive(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POMNET_OPERATION_PKT pHeaderPkt,
|
||
POM_WSGROUP pWSGroup,
|
||
POM_WORKSET pWorkset,
|
||
POM_OBJECT pObj);
|
||
|
||
|
||
//
|
||
// ProcessMessage(...)
|
||
//
|
||
// This function takes a receive control block (generated by ReceiveData)
|
||
// and tries to process it as an ObMan message. If the message can not be
|
||
// processed at this time, it is put on the bounce list. If the message is
|
||
// an "enabling" message (one which might enable previously bounced
|
||
// messages to be processed now) the bounce queue is flushed.
|
||
//
|
||
// Since this function is also called to process bounced messages, and
|
||
// since we want to prevent deep recursion as one bounced "enabling"
|
||
// message prompts re-examination of the bounce queue etc., we use the
|
||
// <whatNext> parameter to determine whether the bounce list should be
|
||
// examined.
|
||
//
|
||
//
|
||
|
||
UINT ProcessMessage(POM_PRIMARY pomPrimary,
|
||
POM_RECEIVE_CB pReceiveCB,
|
||
UINT whatNext);
|
||
|
||
#define OK_TO_RETRY_BOUNCE_LIST 1
|
||
#define DONT_RETRY_BOUNCE_LIST 2
|
||
|
||
//
|
||
// ReceiveData(...)
|
||
//
|
||
UINT ReceiveData(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
PNET_SEND_IND_EVENT pNetSendInd,
|
||
POMNET_OPERATION_PKT pNetMessage);
|
||
|
||
|
||
//
|
||
// TryToSpoilOp
|
||
//
|
||
UINT TryToSpoilOp(POM_SEND_INST pSendInst);
|
||
|
||
|
||
//
|
||
// DecideTransferSize(...)
|
||
//
|
||
void DecideTransferSize(POM_SEND_INST pSendInst,
|
||
UINT * pTransferSize,
|
||
UINT * pDataTransferSize);
|
||
|
||
|
||
//
|
||
// CreateReceiveCB(...)
|
||
//
|
||
UINT CreateReceiveCB(POM_DOMAIN pDomain,
|
||
PNET_SEND_IND_EVENT pNetSendInd,
|
||
POMNET_OPERATION_PKT pNetMessage,
|
||
POM_RECEIVE_CB * ppReceiveCB);
|
||
|
||
|
||
//
|
||
// FindReceiveCB(...)
|
||
//
|
||
UINT FindReceiveCB(POM_DOMAIN pDomain,
|
||
PNET_SEND_IND_EVENT pNetSendInd,
|
||
POMNET_OPERATION_PKT pDataPkt,
|
||
POM_RECEIVE_CB * ppReceiveCB);
|
||
|
||
//
|
||
// WSGRegisterAbort(...)
|
||
//
|
||
void WSGRegisterAbort(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain,
|
||
POM_WSGROUP_REG_CB pRegistrationCB);
|
||
|
||
|
||
//
|
||
//
|
||
// BounceMessage(...)
|
||
//
|
||
// cmf
|
||
//
|
||
//
|
||
|
||
void BounceMessage(POM_DOMAIN pDomain,
|
||
POM_RECEIVE_CB pReceiveCB);
|
||
|
||
|
||
//
|
||
//
|
||
// NewDomainRecord(...)
|
||
//
|
||
//
|
||
|
||
UINT NewDomainRecord(POM_PRIMARY pomPrimary, UINT callID, POM_DOMAIN * ppDomain);
|
||
|
||
void FreeDomainRecord(POM_DOMAIN * ppDomain);
|
||
|
||
|
||
//
|
||
// ProcessBouncedMessages(...)
|
||
//
|
||
void ProcessBouncedMessages(POM_PRIMARY pomPrimary,
|
||
POM_DOMAIN pDomain);
|
||
|
||
|
||
void WSGResetBytesUnacked(POM_WSGROUP pWSGroup);
|
||
|
||
//
|
||
// NewHelperCB()
|
||
// FreeHelperCB()
|
||
//
|
||
BOOL NewHelperCB(POM_DOMAIN pDomain,
|
||
POM_WSGROUP pWSGroup,
|
||
NET_UID lateJoiner,
|
||
OM_CORRELATOR remoteCorrelator,
|
||
POM_HELPER_CB * ppHelperCB);
|
||
|
||
void FreeHelperCB(POM_HELPER_CB * ppHelperCB);
|
||
|
||
|
||
void PurgePendingOps(POM_WORKSET pWorkset, POM_OBJECT pObj);
|
||
|
||
|
||
|
||
OMFP OMMapNameToFP(LPCSTR szName);
|
||
LPCSTR OMMapFPToName(OMFP fp);
|
||
|
||
OMWSG OMMapNameToWSG(LPCSTR szName);
|
||
LPCSTR OMMapWSGToName(OMWSG wsg);
|
||
|
||
|
||
#endif // _H_OM
|
||
|