TipcMsg Class

The TipcMsg class is composed of several parts. These parts consist of a message (C type T_IPC_MSG), and various member functions that manipulate an object of the TipcMsg class.

In the C API, messages, message types, and their associated data are manipulated primarily through functions that begin with the TipcMsg* or TipcMt* prefix. In the C++ class library, the corresponding C++ methods are grouped primarily within two C++ classes called TipcMsg and TipcMt. A third class, called Tobj, manages a status flag used for error checking when manipulating messages and message types in the C++ class library.

You manipulate the type, sender, delivery mode, destination, priority, delivery timeout, load-balancing mode, header string encoding, user-defined field, and read-only properties of a message by calling methods of the TipcMsg class. The data part of a message can be manipulated in two ways, overloaded Append() and Next() member functions, or overloaded insertion and extraction operators (operator<<() and operator>>() respectively). The Append() and Next() member functions are C++ implementations of the C API’s TipcMsgAppend* and TipcMsgNext* functions. The insertion and extraction operators provide an interface similar to IOSTREAM classes for appending and accessing data fields from a message.

It is recommended that the use of Append() and Next() member functions not be mixed with the insertion and extraction operators. The two methods represent different paradigms that may not work well together.

Vacant and Non-Vacant TipcMsg Objects

A vacant TipcMsg object is one that is not currently managing a C type T_IPC_MSG message. Likewise, a non-vacant TipcMsg object is one that is currently managing a C type T_IPC_MSG message. The simple TipcMsg constructor (described in Using A Simple Constructor on page 28) can be used to explicitly create a vacant TipcMsg object. All other constructors create objects that manage a C type T_IPC_MSG. The major difference between a vacant and a non-vacant TipcMsg object is that data fields can only be inserted into and extracted from a non-vacant TipcMsg object.

Vacant TipcMsg objects also appear as a result of an operation on a non-vacant TipcMsg object. A vacant TipcMsg object is created whenever destroy responsibility is taken from the caller, or a member function fails and needs to return a valid TipcMsg object.

These member functions take destroy responsibility from the caller, and also take a non-vacant TipcMsg object and make it vacant:

These member functions may return a vacant TipcMsg object when they fail:

The TipcMsg::Vacant() member function can be used to determine if a TipcMsg object is vacant or non-vacant.