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... |
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.
|
Definition at line 39 of file RemoteMessage.h. |
|
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
Definition at line 157 of file RemoteMessage.cpp. |
|
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.
Definition at line 225 of file RemoteMessage.cpp. |
|
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
After successful completion of the method, envelope can be sent to the receiver via the normal messaging mechanism ( 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.
Definition at line 93 of file RemoteMessage.cpp. |