matlab.net.http.MessageBody - Body of HTTP message - MATLAB (original) (raw)

Namespace: matlab.net.http

Description

A MessageBody object contains the body of an HTTP message. In a request message, set the Body property to your data or to aMessageBody 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.

Creation

A MessageBody object contains the body of an HTTP message. In a request message, set the Body property to your data or to aMessageBody 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

expand all

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 usingimread and imwrite.
• XML DOM — Data converted to or from a string usingxmlread and xmlwrite.
• audio data — Data converted usingaudioread and audiowrite.
• table — Data converted usingreadtable and writetable.
• Other type of array or cell array — Data converted to or from JSON using jsonencode andjsondecode.

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 andcomplete methods try to deduce the type from the data and add the appropriate ContentTypeField to the request message.

In a response message, Data represents theuint8 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 thePayload property.

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

Attributes:

Content-Type of the Data property, specified as a read-onlymatlab.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 callingconvert on the Content-Type field in the message containing thisMessageBody.

You do not set ContentType in a request message. When you create a MessageBody object, this property is empty. When you copyMessageBody 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 setContentType based on the type of Data and the value of the ContentTypeField in the request message.

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

Attributes:

This property is set to indicate that the Payload property of aResponseMessage 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 tofalse, then the unprocessed still-encoded payload is returned inPayload, Data is left empty, andContentCoding 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 inContentCoding. For example, if the value isgzip, you can write the data to a file and use thegunzip command to process the data.

Attributes:

Data Types: string

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 setPayload 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 theUTF-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 toPayload.
• If you do not want output conversion on the byte array, then setPayload 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 ofRequestMessage.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 andPayload 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 theRequestMessage.send method.
• You set the HTTPOptions.SavePayload property totrue.
• Payload is always set for messages appearing in aLogRecord
• If conversion of the payload to MATLAB data failed. For information, check theHTTPException.History property.

Attributes:

Methods

expand all

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

Version History

Introduced in R2016b