matlab.net.http.MessageBody Class

Namespace: matlab.net.http

Body of HTTP message

Description

A MessageBody object contains the body of an HTTP message. In a request message, set the Body property to your data or to a MessageBody object containing your data. In a response message, this object contains the received data.

Message data is represented by two properties. The Payload property contains the raw bytes sent to or received from the network. The Data property contains the Payload as a MATLAB^® type. Often only one of these two properties is set.

Class Attributes

Sealed

true

For information on class attributes, see Class Attributes.

Creation

A MessageBody object contains the body of an HTTP message. In a request message, set the Body property to your data or to a MessageBody object containing your data. In a response message, this object contains the received data.

Message data is represented by two properties. The Payload property contains the raw bytes sent to or received from the network. The Data property contains the Payload as a MATLAB type. Often only one of these two properties is set.

Properties

Data — Message data

uint8 vector or array | character array | string | structure array | image data | XML DOM | audio data | table

Message data, specified as one of the following MATLAB data types. For conversion details, see HTTP Data Type Conversion.

• uint8 vector — Data not converted.

• character array or scalar string — Data converted based on the media type and its charset attribute in the Content-Type header.

• structure array — Data converted to or from JSON string using webread and webwrite.

• image — Data converted to or from an image using imread and imwrite.

• XML DOM — Data converted to or from a string using xmlread and xmlwrite.

• audio data — Data converted using audioread and audiowrite.

• table — Data converted using readtable and writetable.

• Other type of array or cell array — Data converted to or from JSON using jsonencode and jsondecode.

In a request message, the Data property is the MATLAB data before conversion to a uint8 payload. Data conversion happens when you call the RequestMessage send or complete methods. The conversion depends on the Content-Type you specify in the message and the type of Data. If you do not specify a Content-Type, then the send and complete methods try to deduce the type from the data and add the appropriate ContentTypeField to the request message.

In a response message, Data represents the uint8 payload converted to a MATLAB type based on the Content-Type specified by the server. If conversion fails, then Data remains empty and the raw data appears in the Payload property.

To suppress automatic conversion of the response Payload, set the HTTPOptions.ConvertResponse property to false. In that case, Data contains either a string for character data or a uint8 vector of bytes.

Attributes:

GetAccess	public
SetAccess	public
Dependent	true

ContentType — Content-Type of data

MediaType object

Content-Type of the Data property, specified as a read-only matlab.net.http.MediaType object. This property determines how contents of the Data property was converted to or from the payload. If the Content-Type has a MediaType with a charset attribute, then the charset determines the encoding. For more information, see RFC 2616, section 14.17 Content-Type on the RFC Editor website.

This property usually has the same values as the result of calling convert on the Content-Type field in the message containing this MessageBody.

You do not set ContentType in a request message. When you create a MessageBody object, this property is empty. When you copy MessageBody into a request message, ContentType is set to the value of the ContentTypeField in the message, if there is one. The RequestMessage send and complete methods set ContentType based on the type of Data and the value of the ContentTypeField in the request message.

In a response message, ContentType is based on the ContentTypeField of the message.

Attributes:

GetAccess	public
SetAccess	public
Transient	true

ContentCoding — Content-Encoding of payload

string

This property is set to indicate that the Payload property of a ResponseMessage is encoded. When ContentCoding is set, no processing was done on the payload and the Data property is empty.

If MATLAB receives a message whose payload is encoded using a compression algorithm that it supports, such as gzip or deflate, it automatically decodes that payload before attempting any other conversions. If decoding was successful, it optionally stores the decoded payload in Payload and the converted payload (if any) in Data. In that case, this property is empty to indicate that the Payload is not encoded.

If the payload was encoded but decoding was not successful, or you suppressed decoding by setting the HTTPOptions.DecodePayload property to false, then the unprocessed still-encoded payload is returned in Payload, Data is left empty, and ContentCoding is set to a vector of strings representing the value of the Content-Encoding header field in the response message. In this case, you can save the Payload as is (for example, write it to a file), or process it according to the compression algorithms specified in ContentCoding. For example, if the value is gzip, you can write the data to a file and use the gunzip command to process the data.

Attributes:

GetAccess	public
SetAccess	public
Transient	true

Data Types: string

Payload — Raw bytes sent in message

empty (default) | uint8 vector | scalar string | character vector

Raw bytes sent in a message, specified as a uint8 vector, scalar string, or character vector. As a convenience in a request message, you can set Payload to a scalar string or character vector. MATLAB converts the value to a uint8 vector. In a response message, Payload is always a uint8 vector.

In a request message:

• A scalar string or character vector is converted using the charset specified in or implied by the ContentType property, if any, or the UTF-8 encoding if none was set. To use a different encoding, encode it yourself, for example, using the unicode2native function, and assign the resulting uint8 vector to Payload.

• If you do not want output conversion on the byte array, then set Payload instead of the Data property. If you set Data instead, then Payload is filled in with the bytes that were sent if you specify a request or history return argument for RequestMessage.send, in the return value of RequestMessage.complete, or in a ResponseMessage if you set the HTTPOptions.SavePayload property.

• When you set Payload, Data is cleared. If you send a message where both Data and Payload are set, then Payload is sent and Data is ignored. Only response messages and request messages returned by the send or complete methods can have both properties set at the same time.

In a response message, Payload is the raw bytes received in these cases:

• You specify a history return argument in the RequestMessage.send method.

• You set the HTTPOptions.SavePayload property to true.

• Payload is always set for messages appearing in a LogRecord

• If conversion of the payload to MATLAB data failed. For information, check the HTTPException.History property.

Attributes:

GetAccess	public
SetAccess	public
Dependent	true

Methods

Public Methods

show	Display or return formatted version of message body data

Specialized Operators and Functions

These methods specialize standard MATLAB operators and functions for objects in this class.

string	Data property as a string. Use for diagnostics or debugging. If the Data property contains text, then the method displays the entire contents. Use the MessageBody.show method to limit the amount of displayed text. If Data does not contain text, then the method displays a message indicating the length of the data in bytes. If MessageBody is an array, then returns an array of the same size.
char	Data property as a character vector, similar to the string method. However, if MessageBody is an array, then the method returns a cell array of character vectors of the same size.

Version History

Introduced in R2016b