complete

Class: matlab.net.http.RequestMessage
Package: matlab.net.http

Validate and complete HTTP request message without sending

expand all in page

Syntax

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

Description

[completedrequest,target] = complete(request,uri) adds and validates message header fields and converts data like the RequestMessage.send method, but does not send the message. complete assumes a default HTTPOptions object to determine how to complete and validate the request.

Use the complete method to examine the contents of a request message for debugging purposes.

To fill in and validate the Header and RequestLine properties, this method ignores the Completed property in request. The method always returns a modified completedrequest. If request is not completed, then the method errors. You can use this behavior to determine whether a manually completed request is valid.

If Completed is not set, then this method always converts Data in request.Body and stores the result in completedrequest.Body.Payload, overwriting any previous contents of Payload. This means that both Data and Payload in completedrequest.Body contain values. This is different from the behavior of the send which does not save the Payload unless HTTPOptions.SavePayload is set. If the message contains a large amount of data, then memory usage and conversion time might be a factor.

However, if request.Body contains a ContentProvider, then complete does not call the provider to create data. completedrequest.Body contains the same ContentProvider.

example

[completedrequest,target] = complete(request,uri,options) provides additional options for validating and completing the request message.

If you intend to send completedrequest to avoid the cost of a repeat validation, send it to target instead of uri, using the same options. Time-dependent header fields such as Date which are added by the send method, are not updated when sent again using completedrequest.

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.

Additional options, specified as a matlab.net.http.HTTPOptions object, for processing request and response messages.

Output Arguments

expand all

Completed and validated request, returned as a matlab.net.http.RequestMessage object. The Completed property is true.

Completed URI, returned as a matlab.net.URI object.

Examples

expand all

Create a request message for a fictional website. Then, validate and complete the request without sending it.

request = matlab.net.http.RequestMessage();
url = 'myschool.edu/campus.jpg';
options = matlab.net.http.HTTPOptions('SavePayload',true);
[request,url] = complete(request,url,options);
show(request)

GET /campus.jpg HTTP/1.1
Host: myschool.edu
User-Agent: MATLAB/9.0.0.366741 (R2016b)
Date: Wed, 13 Jul 2016 17:21:08 GMT
Connection: close

MATLAB® displays User-Agent and Date values relevant to your system.

Show the updated URL.

string(url)
ans = http://myschool.edu/campus.jpg

Limitations

  • A completed request does not add any authorization header fields that might be needed for authentication to a server or proxy, even if the Authenticate property is set in options. It might not be possible to determine what the server requires without sending the message. To see what was sent in an authentication exchange, examine the completedrequest or history arguments returned by the send method.

Tips

  • To send the same request message repeatedly, send completedrequest. Otherwise, if you send request, then MATLAB repeatedly validates the message. Also be sure to specify target as the URI and the same options input argument. Time-dependent header fields such as Date, which the send method adds, are not updated when sending completedrequest.

  • To complete a message without converting the data, set the Completed property to true before calling the complete method. If Completed is true and request.Body is a MessageBody object, then the complete method assumes that the current value of request.Body.Payload is the desired one, even if it is empty.

    This behavior differs from the send method. If request.Body.Payload is empty, then send converts and sends nonempty Body.Data values, even if Completed is true.

See Also

| | |

Introduced in R2016b

MATLAB Documentation

Support