The CIObject class serves as a base for all other classes; each derived class inherits all functions described here.

CIObject constructor and destructor

The constructor and destructor for CIObject are only accessible for derived classes. The constructor performs all common initialization actions. The destructor performs common cleanup.

CIObject::GetLastError

This call returns the last status returned by an INtime call for the object. After the last call executes successfully, the status is zero (E_OK).

The differences between this call and ::GetLastRtError include:

• ::GetLastRtError returns the last status returned by any INtime call called by the thread.
• CIObject::GetLastError returns the status for the last call applied to a given object.

Syntax

DWORD CIObject::GetLastError(void);

CIObject::Attach

Attaches an RT object handle obtained by an application to the specified object. For example, when an RT object handle is received via a data mailbox.

Syntax

DWORD CIObject::Attach(
    RTHANDLE h
);

Parameters

h

Contains the handle you want to attach. If the object is already attached, it is first detached. The handle must belong to an RT object of a type that corresponds to the object.

Status

E_OK

A successful attach.

E_TYPE

The RT object does not match the object type.

CIObject::Detach

This call breaks the attachment between an object and its RT object; if the RT object was created by the object, the RT object is deleted (using the appropriate INtime call). Using Detach on an object not attached to an RT object has no effect.

Syntax

void CIObject::Detach(void);

Note the difference with the delete operator, which deletes a whole object, including the Detach action.

CIObject::Lookup

To attach an object to an RT object, the name can be looked up in a directory. When this call is used for an object currently attached to an RT object, the RT object is detached (see Detach) when looking up the name fails for whatever reason, the object is left detached.

Syntax

DWORD CIObject::Lookup(
    char * pszName, 
    DWORD dwTimeout
);

Parameters

pszName

Specifies the name to look up; it should not be empty.

dwTimeout

Specifies how long the thread waits if the name is not present and may be omitted (meaning WAIT_FOREVER). The returned value is the status.

Status

E_OK

Indicates a successful lookup.

E_TIME

The name was not found within the given timeout.

E_LIMIT

The specified directory is full and the specified RT object is not yet cataloged.

E_EXIST

The name was found, but the cataloged handle is NULL_RTHANDLE.

E_TYPE

The name was found, but the cataloged RT object was not of the objects type; or the object is a low level object.

E_PARAM

The name has a length of 0 (zero) or greater than 26, or is improperly formatted.

CIObject::GetHandle

This call returns the handle of the RT object currently attached to the object, or NULL_RTHANDLE if no RT object is attached.

Syntax

RTHANDLE  GetHandle(void);

CIObject::GetType

This call returns the type of the object.

Syntax

WORD   GetType(void);

CIObject::Fail (static)

Whenever something irreparable happens, this static class call can be called. It prints a message and the result of ::GetRtLastError if in debug mode and then kills the current process. Fail never returns; it can be called with any object, or with just the class name: CIObject::Fail();

Syntax

static void  Fail(
    char * pszMessage, 
    ...
);
static void  Fail(
    char * pszMessage [,argument]...
);

Assignment operator

The assignment operator detaches the destination operand from its RT object, and then attaches it to the same RT object as the source operand. If the source operand is not connected to an RT object, the destination operand is also left detached. The name of the source operand is copied into the name of the destination operand.

If the two operands do not have the same type, the destination becomes detached and the result is a null object.

Compare operators

The two compare operators (== for equal, != for unequal) verify that both operands are attached to the same RT object; if this is true, the result is "equal" (TRUE for ==, FALSE for !=), otherwise it is "unequal". Note that when either or both operands are not attached, the result is always "unequal". If the two operands do not have the same type, the result is also "unequal".

Member variables

These member variables are available to the member functions of all derived classes, but care must be taken when modifying them:

WORD            m_wType;         // the type
RTHANDLE        m_hRTObject;     // NULL_RTHANDLE if not attached
DWORD           m_status;        // the last status
BOOLEAN         m_bOwner;        // TRUE if this object created the RT object
char            m_cName[13];     // copy of name for uncataloging
RTHANDLE        m_hCatProcess;   // handle of process for (un)cataloging