|
|
//
// 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
|
