TibrvMsg::detach()
Method
Declaration
TibrvMsg* detach();
Purpose
Detach an inbound message from Rendezvous storage; the program assumes responsibility for destroying the message.
Remarks
When Rendezvous software creates a message, it owns that message. This situation occurs only in the case of inbound messages presented to a data callback method; Rendezvous software destroys such messages when the callback method returns, unless the program explicitly detaches the message. After a detach operation, the program owns the message, and must explicitly destroy it to reclaim the storage.
Programs may detach inbound messages. A program cannot detach a message that it already owns; attempts to do so return NULL.
Programs can use this method to detach either an entire message, or a submessage. After detaching a submessage, the program owns that submessage, even after the destruction of the surrounding parent message.
Callback methods receive inbound messages in stack parameters, which evaporate when the callback methods return. Programs detach messages to allow the messages to persist beyond the local context. Consequently, the detach operation returns a new C++ object, which the program can store in a variable with wider scope. The original inbound message becomes invalid, transferring its embedded C message to the new C++ message object.
|
Warning |
Programs may modify messages only with methods that add, remove or update fields. It is illegal to directly modify data storage in a message field. Detaching a message does not change this restriction. For further information, see Do Not Modify Pointer Snapshots, or more generally, Validity of Data Extracted From Message Fields. |