Understanding Message Objects

So far, we have seen that subscribing to a topic involves working with objects of AMPS::Message type. A Message represents a single message to or from an AMPS server. Messages are received or sent for every client/server operation in AMPS.

Header properties

There are two parts of each message in AMPS: a set of headers that provide metadata for the message, and the data that the message contains. Every AMPS message has one or more header fields defined. The precise headers present depend on the type and context of the message. There are many possible fields in any given message, but only a few are used for any given message. For each header field, the Message class contains a distinct property that allows for retrieval and setting of that field. For example, the Message.get_command_id() function corresponds to the commandId header field, the Message.get_batch_size() function corresponds to the BatchSize header field, and so on. For more information on these header fields, consult the AMPS User Guide and AMPS Command Reference.

The Message object contains several different accessors for header fields.

For retrieving the value of fields on a message:

• The getXxx() functions return a Field. The Field contains pointers to the underlying buffer in the Message. Data is not copied until either deepCopy() is called or the Field is converted to another format (such as constructing a std::string from the Field). The value of the Field is only valid for the lifetime of the message unless it is copied using deepCopy().

• The getRawXxx() functions take a pointer and a length. The pointer is assigned to the first byte of the value in the underlying buffer in the Message. The length is set to the length of the value.

To assign values to a field in a message, the Message object provides several different options. The differences between these options are a matter of managing the memory for the value.

• The setXxx() functions copy the value provided into the specified header.

• The assignXxx() functions set the value of the specified header, avoiding a copy if possible. When this function is used, the Message may refer directly to the data passed in. That data should not change or be deallocated while the Message is in use. (Notice, though, that a copy of the message produced using deepCopy will copy the data and can be used safely even if the original data is changed or deallocated.)

60East does not recommend attempting to parse header fields from the raw data of the message, nor does 60East recommend attempting to manipulate the fields of the message without using the accessor methods.

In AMPS, fields sometimes need to be set to a unique identifier value. For example, when creating a new subscription, or sending a manually constructed message, you’ll need to assign a new unique identifier to multiple fields such as CommandId and SubscriptionId. For this purpose, Message provides newXxx() methods for each field that generates a new unique identifier and sets the field to that new value.

getData() method

Access to the data section of a message is provided via the getData() method. The data contains the unparsed data in the message, returned as a series of bytes (a string or const char *). Your application code parses and works with the data.

The AMPS C++ client contains a collection of helper classes for working with message types that are specific to AMPS (for example, FIX, NVFIX, and AMPS composite message types). For message types that are widely used, such as JSON or XML, you can use whichever library you typically use in your environment.

Message Field Reference

The AMPS Command Reference contains a full description of which fields are available and which fields are returned in response to specific commands.