matlab.net.http.MessageBody class

Package: matlab.net.http

Body of HTTP message

expand all in page

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

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 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 xmlread and xmlwrite.

  • 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

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.

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

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

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

expand all

See Also

| | | | | |

Topics

External Websites

Introduced in R2016b

MATLAB Documentation

Support