404 lines
11 KiB
C++
404 lines
11 KiB
C++
/*
|
|
* objkey.h
|
|
*
|
|
* Copyright (c) 1995 by DataBeam Corporation, Lexington, KY
|
|
*
|
|
* Abstract:
|
|
* This is the interface file for the class CObjectKeyContainer. This class
|
|
* manages the data associated with an Object Key. Object Key are used
|
|
* to identify a particular application protocol, whether it is standard or
|
|
* non-standard. When used to identify a standard protocol, the Object Key
|
|
* takes the form of an Object ID which is a series of non-negative
|
|
* integers. This type of Object Key is maintained internally through the
|
|
* use of a UnicodeString object. When used to identify a non-standard
|
|
* protocol, the Object Key takes the form of an H221 non-standard ID which
|
|
* is an octet string of no fewer than four octets and no more than 255
|
|
* octets. In this case the Object Key is maintained internally by using a
|
|
* Rogue Wave string object.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*
|
|
* Author:
|
|
* jbo
|
|
*/
|
|
#ifndef _OBJECT_KEY_DATA_
|
|
#define _OBJECT_KEY_DATA_
|
|
|
|
|
|
/*
|
|
* Macros used by this class.
|
|
*/
|
|
#define MINIMUM_OBJECT_ID_ARCS 3
|
|
#define ITUT_IDENTIFIER 0
|
|
#define ISO_IDENTIFIER 1
|
|
#define JOINT_ISO_ITUT_IDENTIFIER 2
|
|
#define MINIMUM_NON_STANDARD_ID_LENGTH 4
|
|
#define MAXIMUM_NON_STANDARD_ID_LENGTH 255
|
|
|
|
|
|
/*
|
|
* This is the typedef for the structure used to hold the object key data
|
|
* internally.
|
|
*/
|
|
typedef struct
|
|
{
|
|
LPBYTE object_id_key;
|
|
UINT object_id_length;
|
|
LPOSTR poszNonStandardIDKey;
|
|
}
|
|
OBJECT_KEY;
|
|
|
|
/*
|
|
* Class definition:
|
|
*/
|
|
class CObjectKeyContainer : public CRefCount
|
|
{
|
|
public:
|
|
|
|
CObjectKeyContainer(PGCCObjectKey, PGCCError);
|
|
CObjectKeyContainer(PKey, PGCCError);
|
|
CObjectKeyContainer(CObjectKeyContainer *, PGCCError);
|
|
|
|
~CObjectKeyContainer(void);
|
|
|
|
UINT LockObjectKeyData(void);
|
|
void UnLockObjectKeyData(void);
|
|
|
|
UINT GetGCCObjectKeyData(PGCCObjectKey, LPBYTE memory);
|
|
GCCError GetObjectKeyDataPDU(PKey);
|
|
void FreeObjectKeyDataPDU(void);
|
|
|
|
friend BOOL operator== (const CObjectKeyContainer&, const CObjectKeyContainer&);
|
|
|
|
protected:
|
|
|
|
OBJECT_KEY m_InternalObjectKey;
|
|
UINT m_cbDataSize;
|
|
|
|
Key m_ObjectKeyPDU;
|
|
BOOL m_fValidObjectKeyPDU;
|
|
|
|
private:
|
|
|
|
BOOL ValidateObjectIdValues(UINT first_arc, UINT second_arc);
|
|
};
|
|
|
|
/*
|
|
* Comments explaining the public and protected class member functions
|
|
*/
|
|
|
|
/*
|
|
* CObjectKeyContainer ( PGCCObjectKey object_key,
|
|
* PGCCError return_value);
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This is the constructor for the CObjectKeyContainer class which takes as
|
|
* input the "API" version of object key data, GCCObjectKey.
|
|
*
|
|
* Formal Parameters:
|
|
* object_key (i) The object key data to store.
|
|
* return_value (o) The output parameter used to indicate errors.
|
|
*
|
|
* Return Value:
|
|
* GCC_NO_ERROR - No error.
|
|
* GCC_ALLOCATION_FAILURE - Error creating an object using the
|
|
* "new" operator.
|
|
* GCC_BAD_OBJECT_KEY - An invalid object key passed in.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
|
|
/*
|
|
* CObjectKeyContainer ( PKey object_key,
|
|
* PGCCError return_value);
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This is the constructor for the CObjectKeyContainer class which takes as
|
|
* input the "PDU" version of object key data, Key.
|
|
*
|
|
* Formal Parameters:
|
|
* object_key (i) The object key data to store.
|
|
* return_value (o) The output parameter used to indicate errors.
|
|
*
|
|
* Return Value:
|
|
* GCC_NO_ERROR - No error.
|
|
* GCC_ALLOCATION_FAILURE - Error creating an object using the
|
|
* "new" operator.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
|
|
/*
|
|
* CObjectKeyContainer ( CObjectKeyContainer *object_key,
|
|
* PGCCError return_value);
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This is the copy constructor for the CObjectKeyContainer class which takes
|
|
* as input another CObjectKeyContainer object.
|
|
*
|
|
* Formal Parameters:
|
|
* object_key (i) The CObjectKeyContainer object to copy.
|
|
* return_value (o) The output parameter used to indicate errors.
|
|
*
|
|
* Return Value:
|
|
* GCC_NO_ERROR - No error.
|
|
* GCC_ALLOCATION_FAILURE - Error creating an object using the
|
|
* "new" operator.
|
|
* GCC_BAD_OBJECT_KEY - An invalid CObjectKeyContainer passed in.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
|
|
/*
|
|
* ~ObjectKeyData();
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This is the destructor for the CObjectKeyContainer class. It is used to
|
|
* clean up any memory allocated during the life of this object.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
|
|
/*
|
|
* UINT LockObjectKeyData ();
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This routine is used to "lock" the "API" data for this object. This
|
|
* results in the lock count for this object being incremented. When the
|
|
* lock count transitions from 0 to 1, a calculation is made to determine
|
|
* how much memory will be needed to hold any "API" data which will
|
|
* be referenced by, but not held in, the GCCObjectKey structure
|
|
* which is filled in on a call to GetGCCObjectKeyData. This is the
|
|
* value returned by this routine in order to allow the calling object to
|
|
* allocate that amount of memory in preparation for the call to
|
|
* GetGCCObjectKeyData.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* The amount of memory, if any, which will be needed to hold "API" data
|
|
* which is referenced by, but not held in, the GCCObjectKey structure
|
|
* provided as an output parameter to the GetGCCObjectKeyData call.
|
|
*
|
|
* Side Effects:
|
|
* The internal lock count is incremented.
|
|
*
|
|
* Caveats:
|
|
* The internal lock count is used in conjuction with an internal "free"
|
|
* flag as a mechanism for ensuring that this object remains in existance
|
|
* until all interested parties are through with it. The object remains
|
|
* valid (unless explicity deleted) until the lock count is zero and the
|
|
* "free" flag is set through a call to FreeObjectKeyData. This allows
|
|
* other objects to lock this object and be sure that it remains valid
|
|
* until they call UnLock which will decrement the internal lock count. A
|
|
* typical usage scenerio for this object would be: An CObjectKeyContainer
|
|
* object is constructed and then passed off to any interested parties
|
|
* through a function call. On return from the function call, the
|
|
* FreeObjectKeyData call is made which will set the internal "free"
|
|
* flag. If no other parties have locked the object with a Lock call,
|
|
* then the CObjectKeyContainer object will automatically delete itself when
|
|
* the FreeObjectKeyData call is made. If, however, any number of
|
|
* other parties has locked the object, it will remain in existence until
|
|
* each of them has unlocked the object through a call to UnLock.
|
|
*/
|
|
|
|
|
|
/*
|
|
* UINT GetGCCObjectKeyData (
|
|
* PGCCObjectKey object_key,
|
|
* LPSTR memory);
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This routine is used to retrieve the object key data from the
|
|
* CObjectKeyContainer object in the "API" form of a GCCObjectKey.
|
|
*
|
|
* Formal Parameters:
|
|
* object_key (o) The GCCObjectKey structure to fill in.
|
|
* memory (o) The memory used to hold any data referenced by,
|
|
* but not held in, the output structure.
|
|
*
|
|
* Return Value:
|
|
* The amount of data, if any, written into the bulk memory block provided.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
|
|
/*
|
|
* void UnLockObjectKeyData ();
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This routine is used to "unlock" the "API" data for this object. This
|
|
* results in the lock count for this object being decremented. When the
|
|
* lock count transitions from 1 to 0, a check is made to determine
|
|
* whether the object has been freed through a call to
|
|
* FreeObjectKeyData. If so, the object will automatically delete
|
|
* itself.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* The internal lock count is decremented.
|
|
*
|
|
* Caveats:
|
|
* It is the responsibility of any party which locks an CObjectKeyContainer
|
|
* object by calling Lock to also unlock the object with a call to UnLock.
|
|
* If the party calling UnLock did not construct the CObjectKeyContainer
|
|
* object, it should assume the object to be invalid thereafter.
|
|
*/
|
|
|
|
|
|
/*
|
|
* void FreeObjectKeyData ();
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This routine is used to "free" the "API" data for this object. This
|
|
* will result in the automatic deletion of this object if the object is
|
|
* not in the "locked" state.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* The internal "free" flag is set.
|
|
*
|
|
* Caveats:
|
|
* This object should be assumed invalid after a call to
|
|
* FreeObjectKeyData has been made.
|
|
*/
|
|
|
|
|
|
/*
|
|
* GCCError GetObjectKeyDataPDU (
|
|
* PKey object_key);
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This routine is used to retrieve the object key data from the
|
|
* CObjectKeyContainer object in the "PDU" form of a Key.
|
|
*
|
|
* Formal Parameters:
|
|
* object_key (o) The Key structure to fill in.
|
|
*
|
|
* Return Value:
|
|
* GCC_NO_ERROR - No error.
|
|
* GCC_ALLOCATION_FAILURE - Error creating an object using the
|
|
* "new" operator.
|
|
* GCC_BAD_OBJECT_KEY - One of the internal pointers has
|
|
* been corrupted.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
|
|
/*
|
|
* void FreeObjectKeyDataPDU ();
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This routine is used to "free" the "PDU" data allocated for this object
|
|
* which is held internally in a Key structure.
|
|
*
|
|
* Formal Parameters:
|
|
* None.
|
|
*
|
|
* Return Value:
|
|
* None.
|
|
*
|
|
* Side Effects:
|
|
* The internal flag is set to indicate that the PDU form of data no
|
|
* longer is valid for this object.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
|
|
/*
|
|
* friend BOOL operator== (const CObjectKeyContainer& object_key_1,
|
|
* const CObjectKeyContainer& object_key_2);
|
|
*
|
|
* Public member function of CObjectKeyContainer.
|
|
*
|
|
* Function Description:
|
|
* This routine is used to compare two CObjectKeyContainer objects to determine
|
|
* whether or not they are equal in value.
|
|
*
|
|
* Formal Parameters:
|
|
* object_key_1 (i) The first CObjectKeyContainer object to compare.
|
|
* object_key_2 (i) The other CObjectKeyContainer object to compare.
|
|
*
|
|
* Return Value:
|
|
* TRUE - The two objects are equal in value.
|
|
* FALSE - The two objects are not equal in value.
|
|
*
|
|
* Side Effects:
|
|
* None.
|
|
*
|
|
* Caveats:
|
|
* None.
|
|
*/
|
|
|
|
#endif
|