matlab.net.http.io.MultipartProvider Class

Namespace: matlab.net.http.io
Superclasses: matlab.net.http.io.ContentProvider

ContentProvider to send multipart/mixed HTTP messages

expand all in page

Description

This provider helps with the creation of multipart HTTP messages.

The default Content-Type is "multipart/mixed", and the payload of the message contains an arbitrary number of parts, each part containing its own header describing that part. For more information on multipart messages, see RFC 2046, section 5.1 on the RFC Editor website.

Use this provider directly only if you know that your server accepts multipart/mixed messages. Usually, servers that accept multipart messages instead require "multipart/form-data", which is implemented by the subclass MultipartFormProvider. You can implement other multipart types using subclasses.

The matlab.net.http.io.MultipartProvider class is a handle class.

Subclass Authors

Each of the parts of the multipart message can be specified as data in any of the formats permitted for RequestMessage.Body, or as a ContentProvider that creates the data. The ContentProvider objects that are used to supply data for the parts are called delegates, while this MultipartProvider is the top level provider. In general, any ContentProvider is suitable as a delegate. The MultipartProvider invokes each delegate in turn as the message is being sent, calling its methods, such as complete or start, so that the delegate in general need not be aware that it is providing content for a part, rather than for a whole message.

This provider always transmits the RequestMessage as chunked, so it does not include a Content-Length header field in the message or in the headers of any of the parts. While MultipartProvider calls each delegate's expectedContentLength method before sending the part, it only uses the return value (if nonempty) to enforce the length, not to create a Content-Length field. If the delegate does want a Content-Length field to appear in the part, it must insert such a field explicitly in its Header property. None of the ContentProvider subclasses provided by MATLAB® do this processing.

Creation

Description

provider = MultipartProvider(part1,...,partN) constructs a MultipartProvider that sends the specified parts, in the specified order, in an HTTP request. By default this provider sets the Content-Type of the message to "multipart/mixed", but subclasses can alter the subtype by setting the Subtype property. The constructor sets elements of the Parts property cell array to each part1,...,partN argument.

Properties

expand all

Public Properties

Parts of the message body, specified as a cell array of one or more of these values:

ContentProvider object

The MultipartProvider delegates creation of the part to the specified provider (called the delegate), invoking its complete method to obtain header information about the part and its getData method to obtain the data. The delegate's Header property is used for the header of the part. Any subclass of ContentProvider can be specified here. Normally, the delegate does not specify the content length nor implement the expectedContentLength method, since the end of a part is designated by a boundary string rather than a header field. If that method is implemented to return a nonempty value, then the value is used only to enforce the length of the content, not to create a Content-Length field.

RequestMessage object

The MultipartProvider sends the Header and Body of the RequestMessage as the part. If the Body's Payload property is set, then that is used for the raw payload. Otherwise the Body's Data property is converted based on its type or the Content-Type field in the Header, as described for MessageBody.Data. This option is useful if you have data to send and want to take advantage of the default processing of that data that MATLAB normally does when sending a RequestMessage. It allows you to specify custom header fields in the request to be used as the part's Header and control how the data is converted, without having to write a ContentProvider subclass. The RequestMessage.RequestLine property is ignored.

MessageBody object

The MessageBody is processed the same as if it was in a RequestMessage that had no Content-Type field. This option is useful if default processing of the data based on its type is sufficient, and you do not need to specify any custom header fields for the part. MATLAB inserts a Content-Type field in the part based on the type of the data. See MessageBody.Data for conversion rules.

Array of ContentProvider, RequestMessage, and/or MessageBody objects

This treats each element of the array as a part. Not a cell array.

Handle to getData method

This method must have the signature of ContentProvider.getData. In this case, the part's Content-Type is set to "application/octet-stream", so this option is useful for sending binary data. When using this option, you cannot specify any custom header fields for the part.

Any other type

If the type does not match any of these types and is not a function handle, then it is treated as if it was present in the Data property of a MessageBody. See the description for MessageBody types.

Attributes:

GetAccess
public
SetAccess
public
Dependent
true

Header fields of the message or part, specified as a vector of one or more matlab.net.http.HeaderField objects.

This property is only used by subclass authors. MATLAB sets this property before calling the provider's complete method. For non-multipart messages, MATLAB initializes this property to the contents of Request.Header, minus any matlab.net.http.field.GenericFields or empty-valued fields. The ContentProvider uses this property to add header fields that describe the data to be sent, or to add parameters to header fields already in the message. In a delegate for a MultipartProvider, MATLAB initializes this property to header fields that the delegating provider intends to insert for the part. Delegates can modify or change these fields.

Upon return from the provider's complete method, if this not a multipart message, then MATLAB reads this property and merges its contents into the header of Request. Fields in this Header with Names that do not already appear in Request.Header are added to the end of Request.Header. If a field in this Header has a Name that is the same as one in Request.Header, and both have nonempty Values, then:

  • If the one in Request.Header is a GenericField, then ignore the one in Header.

  • If the one in Request.Header is not a GenericField, then replace it with the one in Header.

If one or both of these has an empty Value, then the field is removed from Request.Header and it is not added as part of normal message completion.

If this is a delegate of a MultipartProvider, then the entire contents of this Header is used as the header of the part. Multipart delegates must not assume that Request.Header contains any fields pertaining to their own Header. A provider can determine whether it is a multipart delegate by checking whether MyDelegator is a MultipartProvider, though this test is unlikely to be needed.

MATLAB reads this property only on return from calling the provider's complete method. Changes to this array are ignored once MATLAB calls start.

Class authors should be aware that their subclasses might have added fields to this Header (in their complete method) before calling complete in their superclass. It is best to preserve such fields and not to add fields with the same names. However, adding a parameter to a field is permissible. For example, a superclass can add a charset parameter to an existing Content-Type field that does not already have one.

Attributes:

GetAccess
public
SetAccess
public

Indicate whether to force chunked transfer coding, specified as boolean. This property is of interest only to subclass authors, and is applicable only to providers that are not multipart delegates. Subclasses set ForceChunked to control whether contents should be sent using chunked transfer coding. If false (default), MATLAB decides whether to send the contents chunked, based on whether it knows the content length at the time the message is ready to be sent:

  • If MATLAB knows the content length (which is the case if the message contains a Content-Length field, or if this provider's expectedContentLength method returned a number), then MATLAB decides whether to send it chunked or not.

  • If MATLAB does not know the content length (no Content-Length field in the header and expectedContentLength returned empty), then MATLAB always sends the message chunked.

If ForceChunked is true, then MATLAB sends the message chunked regardless of whether it knows the content length, unless the known length is smaller than the chunk size. If this property is true, then the message must not contain a Content-Length field, because HTTP does not allow a chunked message to have a Content-Length field. However, you can still return a nonzero value in the expectedContentLength method if you want MATLAB to verify that you are returning the expected length of data.

When MATLAB chooses to send the message chunked, the size of each chunk is equal to the length of data returned by getData.

MATLAB reads this value after calling the complete method, before calling start. It does not set this field.

Attributes:

GetAccess
public
SetAccess
public

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

This property is used only by subclass authors. The RequestMessage.send and RequestMessage.complete methods set this property to the RequestMessage in whose Body this provider has been placed, before calling any other methods in this provider, and before adding any additional header fields or validating the message. The provider can examine this message to see what was contained in the original request.

Delegates see the same value for this property as the delegator. ContentProviders should be aware that, if they are delegates, they are not necessarily providing the entire body of the request message, so they should not assume that header fields in this Request are pertinent to the data they are providing. Usually, delegates should ignore header fields in this request relevant to the data, such as Content-Type.

If the provider wishes to add any header fields to this message, or to modify existing ones, it should do so in its complete method by adding those fields to the Header property. The caller of complete (RequestMessage or a delegating provider) determines what to do with those fields. RequestMessage.send and RequestMessage.complete always copy these fields to the Header of the RequestMessage. A delegating provider can copy the fields to its own Header property or insert them into the message (as in the case of MultipartProvider). For more information, see the Header property.

This property is read-only.

Attributes:

GetAccesspublic
SetAccessmatlab.net.http.RequestMessage

Protected Properties

Provider subtype, specified as a string. The default value "mixed" adds a Content-Type header set to "multipart/mixed" to the message, plus appropriate parameters. Subclasses can alter this value in the constructor or the complete method. This value appears in the Content-Type after "multipart/".

Attributes:

GetAccess
protected
SetAccess
protected

ContentProvider to which this provider is delegating, specified as a matlab.net.http.io.ContentProvider object. This property is set in the calling provider (the delegator) by the delegateTo method to indicate the current delegated provider. If there is no current delegation, then the value is empty.

The complete methods set this property to empty.

Attributes:

GetAccess
protected
SetAccess
protected

ContentProvider that delegated to this provider, specified as a matlab.net.http.io.ContentProvider object.

If a ContentProvider delegates responsibility for sending all or a portion of the message data to another provider, then this property identifies the delegating provider to the delegate. For example, a MultipartProvider delegates parts of the message to other providers, so it inserts a handle to itself in each delegate. Otherwise, MyDelegator is empty. The delegateTo method sets this property in the delegate.

Attributes:

GetAccess
protected
SetAccess
protected

Methods

expand all

More About

expand all

Version History

Introduced in R2018a

See Also

| | | |