send

Class: matlab.net.http.RequestMessage
Namespace: matlab.net.http

Send HTTP request message and receive response

expand all in page

Syntax

[response,completedrequest,history] = send(request,uri)
[response,completedrequest,history] = send(request,uri,options,consumer)

Description

[response,completedrequest,history] = send(request,uri) sends the request message to the web service specified by uri and returns the response, if any. If no request.Method property is specified, then the send method sets the property to 'GET'.

By default, send verifies the semantic correctness of the headers and other parts of the message and completes the uri. The method also fills in any required header fields for a properly formed request. If request.Body is a MessageBody whose Payload property is not already set, then send calls appropriate conversion functions to convert any request.Body.Data to a vector of bytes representing an HTTP payload to be sent, as described for MessageBody.Data. Normally, a 'GET' request does not contain data, but the method sends the Body regardless of the RequestMethod. If the server returns data in its response and no consumer is specified, then send converts that data to MATLAB® data and saves it in response.Body.Data. See MessageBody.Data for more information on data conversion.

If request.Body is a ContentProvider, then MATLAB calls the provider to get the data to be sent.

If the header already contains a field that the method normally adds, then send verifies that the field has the expected value. You can override the default behavior as follows.

  • To send a message as is without any checking or alteration of the header, set the request.Completed property to true before sending. If you used the complete method to complete the request, then you should specify the same value of uri and options that you provided to complete, or there might be unpredictable results. Even if Completed is set, unspecified fields in the RequestLine will be filled in with default values.

  • To allow the send method to check and alter the header, but suppress adding a particular header field that send or a ContentProvider might add, add that field to request.Header with an empty value ([]). For example, send automatically adds a User-Agent header field. If you do not want this behavior, then add HeaderField('User-Agent') to the header. Header fields with empty values are not included in the message. The Host and Connection fields cannot be suppressed.

  • To override the value that the send method adds for a given header field, add your own instance of that field before sending or completing the message. However, this will not override a header field that a ContentProvider might add. However, for some header field types, send might still reject the message if the value is not valid. To prevent any checking of the value of a given field, or to override a field that a ContentProvider adds, add a field of type matlab.http.field.GenericField to the header with the desired name and value. Neither send nor a ContentProvider will add any header fields with names equal to any GenericField headers and will not check their correctness.

  • To send raw binary data without conversion, you can insert a uint8 vector into either Body.Data or Body.Payload. The only difference is that data in Body.Data is subject to conversion based on the Content-Type field in the message, while Body.Payload is not. send always tries to convert nonempty Body.Data if Body.Payload is empty, even if Completed is already set. See MessageBody.Data for conversion rules.

example

[response,completedrequest,history] = send(request,uri,options,consumer) provides additional options for processing the request and response messages.

example

Input Arguments

expand all

Request message, specified as a matlab.net.http.RequestMessage object.

Message destination, specified as a matlab.net.URI object or a string or character vector acceptable to the constructor. If the value is a URI object, then it must name a Host. If it is a string and it does not include a Scheme, then 'http' is assumed. For example, 'www.somewebsite.com' and '//www.somewebsite.com' are both treated as 'http://www.somewebsite.com'.

Additional options, specified as a matlab.net.http.HTTPOptions object, for processing request and response messages. If not specified, or if the value is empty, then send uses default options.

Content consumer to process the returned payload, specified as a matlab.net.http.io.ContentConsumer object or a handle to a function that returns a ContentConsumer.

The send method calls the ContentConsumer to process or store buffers of data in real time as the data is being received. The consumer can store the data in response.Body.Data or handle it in some other way. For example, a consumer can display the data in a figure window or save it in a file. When a consumer is specified, MATLAB does not automatically set MessageBody.Data, but it will set MessageBody.Payload to the unconverted payload if options.SavePayload is true. For example, a FileConsumer saves the data to a file, not in MessageBody.Data.

Using a ContentConsumer provides more flexibility in converting or storing the response data than the default MATLAB response data conversion. For a description of the default conversion of received data, see MessageBody.Data. For a list of ContentConsumer types provided by MATLAB, type:

mp = ?matlab.net.http.io.ContentConsumer;
{mp.ContainingPackage.ClassList.Name}'

In addition, software developers can create their own ContentConsumer subclasses to process data as it is being received.

The consumer is used only if it accepts the message, based on various factors such as the Content-Type header in the response and whether response.StatusCode is OK. Each consumer has its own criteria for accepting a message.

If the payload is compressed with a supported encoding, and options is unspecified or options.DecodePayload is true, then the consumer gets the decompressed data. If payload is compressed and options.DecodePayload is false, or the payload is compressed with an unsupported encoding, then the consumer is not used and there is no default processing of the data.

In all cases where the consumer is not used, the payload is processed and converted as if no consumer was specified.

If consumer is a function handle, the function is called to instantiate a consumer only after MATLAB determines that the response has a payload.

When specifying consumer but no options, add a placeholder [] argument for options to use default options.

Output Arguments

expand all

Message received from a server, returned as a matlab.net.http.ResponseMessage object. There might be intermediate requests and responses exchanged between MATLAB and the proxy or server if redirections and/or authentications are involved.

Request that was sent before receiving the response argument, returned as a matlab.net.http.RequestMessage object. The send method augments the completedrequest argument with authentication or redirection information.

If request.Body is a ContentProvider, then completedrequest.Body is normally empty because ContentProvider payloads are not saved. However, if options.SavePayload is true, then the completedrequest.Body is a MessageBody whose Payload has the data sent from the provider as a uint8 vector. In some cases, when the Content-Type of the request indicates that it is character-based, the MessageBody.Data property contains the payload represented as a string.

After sending an HTTP request, examine the completedrequest argument to see what was sent. The server might send multiple messages, for example, if there were redirections or an authentication exchange occurred. If there are multiple messages, then completedrequest contains the last request. To see the first, or intermediate messages, look at the history argument.

To send the same request multiple times, call the RequestMessage.complete method:

[completedrequest,target] = complete(request,uri)

Then, call the send method with these output arguments:

resp = send(completedrequest,target)

Log of messages, returned as a vector of matlab.net.http.LogRecord objects that were exchanged to satisfy this send request. If you have a single request and response, then the history argument contains one record. In the case of an authentication containing multiple messages, the history can contain multiple log records for each redirection.

Use the history to obtain all Set-Cookie headers from response messages. You can send these headers back to the server in subsequent requests.

The last record in the history contains the same properties as the completedrequest and response arguments, except for the Body property. To log message bodies, specify the SavePayload property in the options argument.

The history also can be useful for debugging.

Examples

expand all

Open Script

Send an HTTP message to read the MathWorks Contact Support web page and display the message status code.

import matlab.net.*
import matlab.net.http.*
r = RequestMessage;
uri = URI('https://www.mathworks.com/support/contact_us');
resp = send(r,uri);
status = resp.StatusCode

status = 

    OK
Open Script

Prevent message redirects from mathworks.com website by setting the HTTP option MaxRedirects to zero. Then display status code information.

import matlab.net.*
import matlab.net.http.*
r = RequestMessage;
uri = URI('https://www.mathworks.com/support/contact_us');
options = HTTPOptions('MaxRedirects',0);
[resp,~,hist] = send(r,uri,options);
status = getReasonPhrase(resp.StatusCode)

status =

    'Moved Permanently'

Error Handling

Always check the response Status property to determine whether the request was accepted. Error conditions are:

  • MException — Message is not well formed and cannot be completed.

  • HTTPException — Message is completed, but the web service is unreachable or does not respond within the timeout period specified in options.

  • Status property of response — Web service responds and returns an HTTP error status. send returns normally, setting the Status property to the error returned from the server.

Version History

Introduced in R2016b

See Also

| | | | | | |