matlab.net.http.RequestMessage Class

Namespace: matlab.net.http
Superclasses: matlab.net.http.Message

HTTP request message

Description

Use the RequestMessage class to format HTTP request messages to send to a server for processing. Use the send method to send the message, or the complete method to validate the message before sending. These methods fill in any necessary header fields and other message properties.

Class Attributes

Sealed

true

For information on class attributes, see Class Attributes.

Creation

Description

obj = matlab.net.http.RequestMessage creates a request message with default values. When you send or complete a message, the default Method property is RequestMethod.GET.

obj = matlab.net.http.RequestMessage(method,header,body) specifies one or more optional message properties. You can omit trailing arguments and use [] to specify any placeholders.

obj = matlab.net.http.RequestMessage(requestLine,header,body) sets the RequestLine property to requestLine. Use this syntax if you need control over the contents of the request line. For example, to send a message explicitly to a proxy, set the RequestLine.RequestTarget property to the full URI. Otherwise, MATLAB chooses the proxy based on your proxy settings, and the send method sets the RequestTarget to the Path property of the URI.

obj = matlab.net.http.RequestMessage(requestLine,header,provider) gets the message body data from a matlab.net.http.io.ContentProvider.

Properties

RequestLine — Request line

matlab.net.http.RequestLine object | string | character vector

Request line, specified as a matlab.net.http.RequestLine object, or a string or a character vector that contains the method, target, and protocol version. This line is automatically created when you send a message, based on the method and URI you specify. If you set this property explicitly, then its contents are used as the request line. The value might be set to a RequestLine object or to a string which is parsed and converted to a RequestLine object.

Example: 'GET HTTP/1.1'

Attributes:

GetAccess	public
SetAccess	public
Dependent	true

Method — Request method

[] (default) | matlab.net.http.RequestMethod enumeration | string | character vector

Request method, specified as a matlab.net.http.RequestMethod enumeration or a string or character vector representing a request method. To send a message, set the RequestMessage.Method property or the RequestLine.Method property.

Example: 'GET'

Attributes:

GetAccess	public
SetAccess	public
Dependent	true

Header — Message header

[] (default) | matlab.net.http.HeaderField object

Message header, specified as a matlab.net.http.HeaderField object or a vector of HeaderField objects. When you set the Header property, MATLAB^® checks the fields of the header to ensure that they are appropriate for the message type. The RequestMessage send and complete methods fill in any required header fields for a properly formed request.

Attributes:

GetAccess	public
SetAccess	public

Body — Message body

[] (default) | matlab.net.http.MessageBody object | matlab.net.http.io.ContentProvider

Message body, specified as a matlab.net.http.MessageBody object, matlab.net.http.io.ContentProvider, or data acceptable to the MessageBody constructor. By default, Body is empty (set to []). A request message containing a Body property must use a method such as 'PUT' or 'POST', not the default value 'GET'.

In a completed or received message, if the message has a ContentTypeField header field, then the MessageBody.ContentType property is set to that value. Otherwise, ContentType is unchanged or empty.

Attributes:

GetAccess	public
SetAccess	public

Completed — Whether message is complete

false (default) | true

Whether message is complete, specified as true or false. A true value means that the message was completed.

Methods that validate messages (RequestMessage.send and RequestMessage.complete) set the Completed property to true after:

• Determining that the message is valid.

• Completing processing, such as adding required header fields and converting the data.

If the property is true, then these methods do not modify the message, and the send method sends the message without checking it for validity. Any change to this message after that changes the Completed property back to false.

To send arbitrary headers and data in a request message, set Completed to true to prevent the send method from modifying the message. You can still use the complete method to validate the message, but the send method sends it whether it is valid.

If a request message contains data (the Body.Data property is not empty), then Completed is set to true only if Body.Payload contains the raw data. In a response message, the payload is set only if you specify the HTTPOptions.SavePayload property.

Attributes:

GetAccess	public
SetAccess	public
Transient	true

Data Types: logical

StartLine — Message start line

matlab.net.http.StartLine

Message start line, specified as a matlab.net.http.StartLine object.

Attributes:

GetAccess	public
SetAccess	public

Methods

Public Methods

complete	Validate and complete HTTP request message without sending
send	Send HTTP request message and receive response
addFields	Add fields to message header
changeFields	Change existing fields in message header
getFields	Return message header fields matching name or class
removeFields	Remove fields from message header
replaceFields	Change values in or add fields to message header
show	Display or return formatted version of message

Specialized Operators and Functions

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

string	Message Header, Body and StartLine properties, as string. For multiple messages, returns a string array. If Body contains binary data that cannot be converted to characters, then the method displays a message indicating the length of the data in bytes. The string is an approximate representation of what the message looks like when sent or received. Use for logging, diagnostics, or debugging. For a formatted version of messages, use show.
char	Same as string, except returns message as character vector.
isequal	Returns true if the visible public properties of all messages in the two message arrays are equal.

Examples

Create HTTP Request Message

Format an HTTP message requesting a server to add text to a website. This example only formats the message and does not send the data.

Add content to the message body.

data = 'Data to send';
body = matlab.net.http.MessageBody(data);
body.show

Data to send

Create a Content-Type header field describing the data type of the body.

contentTypeField = matlab.net.http.field.ContentTypeField('text/plain');

Create an Accept header field specifying the data types acceptable in the response message.

type1 = matlab.net.http.MediaType('text/*');
type2 = matlab.net.http.MediaType('application/json','q','.5');
acceptField = matlab.net.http.field.AcceptField([type1 type2]);

Create a request header containing the two header fields.

header = [acceptField contentTypeField];

Specify that this message is a PUT request.

method = matlab.net.http.RequestMethod.PUT;

Create the request message and display the contents.

request = matlab.net.http.RequestMessage(method,header,body);
show(request)

PUT
Accept: text/*, application/json; q=.5
Content-Type: text/plain

Data to send

Version History

Introduced in R2016b