372 lines
10 KiB
C
372 lines
10 KiB
C
|
/*
|
||
|
|
* capid.h
|
||
|
|
*
|
||
|
|
* Copyright (c) 1995 by DataBeam Corporation, Lexington, KY
|
||
|
|
*
|
||
|
|
* Abstract:
|
||
|
|
* This is the interface file for the class CCapIDContainer. A
|
||
|
|
* CCapIDContainer object is used to maintain information about
|
||
|
|
* a particular capability of an application. A capability identifier can
|
||
|
|
* be either a standard type or a non-standard type. When the type is
|
||
|
|
* standard, the identifier is stored internally as an integer value. When
|
||
|
|
* the type is non-standard, an CObjectKeyContainer container object is used
|
||
|
|
* internally to buffer the necessary data. In this case the identifier
|
||
|
|
* data may exist as an Object ID which is a series of non-negative
|
||
|
|
* integers or an H221 non-standard ID which is an octet string of no fewer
|
||
|
|
* than four octets and no more than 255 octets.
|
||
|
|
*
|
||
|
|
* Caveats:
|
||
|
|
* None.
|
||
|
|
*
|
||
|
|
* Author:
|
||
|
|
* jbo
|
||
|
|
*/
|
||
|
|
#ifndef _CAPABILITY_IDENTIFIER_DATA_
|
||
|
|
#define _CAPABILITY_IDENTIFIER_DATA_
|
||
|
|
|
||
|
|
#include "objkey.h"
|
||
|
|
|
||
|
|
/*
|
||
|
|
* This is the typedef for the structure used to hold the capability identifier
|
||
|
|
* data internally.
|
||
|
|
*/
|
||
|
|
typedef struct
|
||
|
|
{
|
||
|
|
GCCCapabilityIDType capability_id_type;
|
||
|
|
|
||
|
|
union
|
||
|
|
{
|
||
|
|
USHORT standard_capability;
|
||
|
|
CObjectKeyContainer *non_standard_capability;
|
||
|
|
} u;
|
||
|
|
}
|
||
|
|
CAP_ID_STRUCT;
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Class definition:
|
||
|
|
*/
|
||
|
|
class CCapIDContainer : public CRefCount
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
|
||
|
|
CCapIDContainer(PGCCCapabilityID, PGCCError);
|
||
|
|
CCapIDContainer(PCapabilityID, PGCCError);
|
||
|
|
CCapIDContainer(CCapIDContainer *, PGCCError);
|
||
|
|
|
||
|
|
~CCapIDContainer(void);
|
||
|
|
|
||
|
|
UINT LockCapabilityIdentifierData(void);
|
||
|
|
void UnLockCapabilityIdentifierData(void);
|
||
|
|
|
||
|
|
UINT GetGCCCapabilityIDData(PGCCCapabilityID, LPBYTE memory);
|
||
|
|
GCCError GetCapabilityIdentifierDataPDU(PCapabilityID);
|
||
|
|
void FreeCapabilityIdentifierDataPDU(void);
|
||
|
|
|
||
|
|
friend BOOL operator== (const CCapIDContainer&, const CCapIDContainer&);
|
||
|
|
|
||
|
|
protected:
|
||
|
|
|
||
|
|
CAP_ID_STRUCT m_InternalCapID;
|
||
|
|
UINT m_cbDataSize;
|
||
|
|
|
||
|
|
CapabilityID m_CapIDPDU;
|
||
|
|
BOOL m_fValidCapIDPDU;
|
||
|
|
};
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Comments explaining the public and protected class member functions
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*
|
||
|
|
* CCapIDContainer ( PGCCCapabilityID capability_id,
|
||
|
|
* PGCCError return_value);
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* Function Description:
|
||
|
|
* This is the constructor for the CCapIDContainer class which
|
||
|
|
* takes as input the "API" version of capability ID data, GCCCapabilityID.
|
||
|
|
*
|
||
|
|
* Formal Parameters:
|
||
|
|
* capability_id (i) The capability ID 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_CAPABILITY_ID - An invalid capability ID passed in.
|
||
|
|
*
|
||
|
|
* Side Effects:
|
||
|
|
* None.
|
||
|
|
*
|
||
|
|
* Caveats:
|
||
|
|
* None.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/*
|
||
|
|
* CCapIDContainer ( PCapabilityID capability_id,
|
||
|
|
* PGCCError return_value);
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* Function Description:
|
||
|
|
* This is the constructor for the CCapIDContainer class which
|
||
|
|
* takes as input the "PDU" version of capability ID data, CapabilityID.
|
||
|
|
*
|
||
|
|
* Formal Parameters:
|
||
|
|
* capability_id (i) The capability ID 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_CAPABILITY_ID - An invalid capability ID passed in.
|
||
|
|
*
|
||
|
|
* Side Effects:
|
||
|
|
* None.
|
||
|
|
*
|
||
|
|
* Caveats:
|
||
|
|
* None.
|
||
|
|
*/
|
||
|
|
/*
|
||
|
|
* CCapIDContainer(CCapIDContainer *capability_id,
|
||
|
|
* PGCCError return_value);
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* Function Description:
|
||
|
|
* This is the copy constructor for the CCapIDContainer class
|
||
|
|
* which takes as input another CCapIDContainer object.
|
||
|
|
*
|
||
|
|
* Formal Parameters:
|
||
|
|
* capability_id (i) The CCapIDContainer 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_CAPABILITY_ID - An invalid CCapIDContainer
|
||
|
|
* passed in.
|
||
|
|
*
|
||
|
|
* Side Effects:
|
||
|
|
* None.
|
||
|
|
*
|
||
|
|
* Caveats:
|
||
|
|
* None.
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* ~CapabilityIdentifierData();
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* Function Description:
|
||
|
|
* This is the destructor for the CCapIDContainer 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 LockCapabilityIdentifierData ();
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* 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 GCCCapabilityID structure
|
||
|
|
* which is filled in on a call to GetGCCCapabilityIDData. 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
|
||
|
|
* GetGCCCapabilityIDData.
|
||
|
|
*
|
||
|
|
* 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 GCCCapabilityID structure
|
||
|
|
* provided as an output parameter to the GetGCCCapabilityIDData 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 FreeCapabilityIdentifierData. This
|
||
|
|
* allows other objects to lock this object and be sure that it remains
|
||
|
|
* valid until they call UnLock which will decrement the internal lock
|
||
|
|
* count. A typical usage scenerio for this object would be: A
|
||
|
|
* CCapIDContainer object is constructed and then passed off to
|
||
|
|
* any interested parties through a function call. On return from the
|
||
|
|
* function call, the FreeCapabilityIdentifierData call is made which will
|
||
|
|
* set the internal "free" flag. If no other parties have locked the
|
||
|
|
* object with a Lock call, then the CCapIDContainer object will
|
||
|
|
* automatically delete itself when the FreeCapabilityIdentifierData 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 GetGCCCapabilityIdentifierData (
|
||
|
|
* PGCCCapabilityID capability_id,
|
||
|
|
* LPSTR memory);
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* Function Description:
|
||
|
|
* This routine is used to retrieve the capability ID data from the
|
||
|
|
* CCapIDContainer object in the "API" form of a GCCCapabilityID.
|
||
|
|
*
|
||
|
|
* Formal Parameters:
|
||
|
|
* capability_id (o) The GCCCapabilityID 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 UnLockCapabilityIdentifierData ();
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* 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
|
||
|
|
* FreeCapabilityIdentifierData. 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 a
|
||
|
|
* CCapIDContainer object by calling Lock to also unlock the
|
||
|
|
* object with a call to UnLock. If the party calling UnLock did not
|
||
|
|
* construct the CCapIDContainer object, it should assume the
|
||
|
|
* object to be invalid thereafter.
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* GCCError GetCapabilityIdentifierDataPDU (
|
||
|
|
* PCapabilityID capability_id);
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* Function Description:
|
||
|
|
* This routine is used to retrieve the capability ID data from the
|
||
|
|
* CCapIDContainer object in the "PDU" form of a CapabilityID.
|
||
|
|
*
|
||
|
|
* Formal Parameters:
|
||
|
|
* capability_id (o) The CapabilityID 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 FreeCapabilityIdentifierDataPDU ();
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* Function Description:
|
||
|
|
* This routine is used to "free" the "PDU" data allocated for this object
|
||
|
|
* which is held internally in a CapabilityID structure.
|
||
|
|
*
|
||
|
|
* 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
|
||
|
|
* FreeCapabilityIdentifierDataPDU has been made.
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
* friend BOOL operator== (
|
||
|
|
* const CCapIDContainer& capability_id_1,
|
||
|
|
* const CCapIDContainer& capability_id_2);
|
||
|
|
*
|
||
|
|
* Public member function of CCapIDContainer.
|
||
|
|
*
|
||
|
|
* Function Description:
|
||
|
|
* This routine is used to compare two CCapIDContainer objects
|
||
|
|
* to determine whether or not they are equal in value.
|
||
|
|
*
|
||
|
|
* Formal Parameters:
|
||
|
|
* capability_id_1 (i) The first CCapIDContainer object
|
||
|
|
* to compare.
|
||
|
|
* capability_id_2 (i) The other CCapIDContainer 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
|