Main Page   Namespace List   Compound List   File List   Namespace Members   Compound Members  

RemoteMessage Namespace Reference

Features functions that simplify sending data via messages. More...


Enumerations

enum  {
  RMESSAGE_DATA = 'RMda',
  RMESSAGE_DELIVERY_FAILED = 'RMdf',
  RMESSAGE_DELIVERY_TIMED_OUT = 'RMto'
}

Functions

_IMPEXP_RMESSAGE status_t SetData ( BMessage* envelope, const void* data, size_t size, BMessage* parameters = NULL)
 Prepares an envelope for sending data via a BMessage. More...

_IMPEXP_RMESSAGE status_t GetData ( const BMessage* envelope, const void** data, size_t* size, BMessage* parameters = NULL, bool* hasParameters = NULL)
 Retrieves the data from a data message envelope. More...

_IMPEXP_RMESSAGE status_t ReleaseData (const void* data, size_t size)
 Releases the data retrieved from a data message envelope. More...


Detailed Description

Features functions that simplify sending data via messages.

Although the namespace is called RemoteMessage these functions have nothing to do with remote messaging directly. They just implement a protocol how data shall be stuffed into and extracted from an envelope message. The link to the remote messaging is that this protocol is explicitly supported by the RMessageServer, so that it 1) works at all, and 2) should be relatively efficient (the data is copied as few times as possible).

SetData() finds out, which area the data lives in and at which offset and put those information into the envelope message.

GetData() extracts these information and clones the original area read-only.

ReleaseData() deletes the cloned area when the receiver is done with the data.

There's apparently no benefit, when the amount of data is small. In fact in those cases the additional overhead should make it even slower than just adding the data to the message. The protocol may be improved later to do just that.


Enumeration Type Documentation

anonymous enum
 

Enumeration values:
RMESSAGE_DATA   BMessage::what value identifying a data message.
RMESSAGE_DELIVERY_FAILED   BMessage::what value identifying a message that is sent, when the delivery of a remote message failed for any reason.

The message will contain a "error" field of type B_INT32_TYPE with the exact error that occurred.

RMESSAGE_DELIVERY_TIMED_OUT   BMessage::what value identifying a message that is sent, when the delivery of a remote message timed out.

Definition at line 39 of file RemoteMessage.h.


Function Documentation

status_t RemoteMessage::GetData ( const BMessage * envelope,
const void ** _data,
size_t * _size,
BMessage * parameters = NULL,
bool * _hasParameters = NULL )
 

Retrieves the data from a data message envelope.

Note that the caller must invoke ReleaseData() when done with the data, before replying to or deleting the envelope.

The sent data may be empty, in which case NULL will be returned in data and 0 in size.

Parameters:
envelope   the envelope message from which to get the data.
data   pointer to a variable that shall be set to point to the data. Must not be NULL.
size   pointer to a variable that shall be set to the size of the data.
parameters   pointer to a BMessage that shall be initialized to the parameters contained in the envelope. May be NULL.
hasParameters   pointer to a boolean variable that shall be set to true, if the envelope contains a parameter message, to false otherwise. May be NULL. If parameters is NULL, hasParameters will be ignored, too.
Returns:
  • B_OK: Everything went fine.
  • another error code otherwise.

Definition at line 157 of file RemoteMessage.cpp.

status_t RemoteMessage::ReleaseData ( const void * data,
size_t size )
 

Releases the data retrieved from a data message envelope.

The area that contains the data will be released. After the function returns the data must not be accessed.

There is no need to call this function for zero-sized data, though it does no harm.

Parameters:
data   the data.
size   the size of the data.
Returns:
  • B_OK: Everything went fine.
  • another error code otherwise.

Definition at line 225 of file RemoteMessage.cpp.

status_t RemoteMessage::SetData ( BMessage * envelope,
const void * data,
size_t size,
BMessage * parameters = NULL )
 

Prepares an envelope for sending data via a BMessage.

data and size specify the data to be sent, and parameters is an optional message to be sent together with the data -- usally providing the receiver with additional information concerning the data.

While the contents of parameters can be arbitrary, envelope has a strict format and must not be manipulated by the caller afterwards. The method will set its what field to RMESSAGE_DATA and empty it of data first, and then add fields according to the given parameters.

After successful completion of the method, envelope can be sent to the receiver via the normal messaging mechanism (BMessenger).

The receiver will call GetData() on the envelope, which will clone the area the data live in. By convention the receiver shall not reply to the message until they're done with the data, and the sender shall not modify the data until the receiver's reply arrived.

Parameters:
envelope   the envelope message to contain the data.
data   the data to be sent. May be NULL in which case size must be 0.
size   the number of bytes to be sent.
parameters   an additional message to be sent together with the data. May be NULL.
Returns:
  • B_OK: Everything went fine.
  • another error code otherwise.

Definition at line 93 of file RemoteMessage.cpp.


Generated at Mon Mar 22 02:35:22 2004 for RMessage by doxygen1.2.1 written by Dimitri van Heesch, © 1997-2000