HTTP Data Type Conversion - MATLAB & Simulink (original) (raw)

The MATLAB® HTTP interface automatically converts data types used in HTTP messages to and from MATLAB types.

Converting Data in Request Messages

When sending a message with a payload, assign your MATLAB data to the Data property in a MessageBody object, then send it as a Body property in a RequestMessage object. The type of your MATLAB data depends on the HTTP Content-Type of the message. If you do not specify a Content-Type, then MATLAB assumes Content-Type values, as described in Content-Type Not Specified.

This table shows how MATLAB converts Data to a payload in a request message based on the type/subtype properties and the charset attribute that you specify in the Content-Type header field. The asterisk character (*) means any subtype.

Content-Type MATLAB Type in MessageBody.Data Property
application/json Data converted to a Unicode® value using the jsonencode function. MATLAB then uses the unicode2native function to convert the value to uint8, based on the charset attribute in the Content-Type header field.If you already have JSON-encoded text, then assign the text to the Payload property instead of the Data property. MATLAB converts the value to uint8 using the charset attribute.If the charset attribute is not specified, then the default charset value isUTF-8.
text/* for any subtype other thancsv orxml If Data is a character or string array or a cell array of character vectors, MATLAB reshapes and concatenates the text by row to form a vector.If Data is any other type, MATLAB converts Data using thestring function. The resulting string is converted to uint8 based on the charset.If you did not specify a charset, the default depends on the subtype. For the following subtypes, the default is UTF-8:jsonjtmljavascriptcsscalendarFor all other subtypes, MATLAB determines the charset. If all characters are in the ASCII range, then the charset isUS-ASCII. Otherwise, the charset isUTF-8.NoteServers might not properly interpret text types encoded asUTF-8 without an explicitUTF-8 charset. For best results, explicitly specify UTF-8 if your data contains non-ASCII characters.
image/* Data must be image data in a form acceptable to the imwrite function. Conversion of Data touint8 depends on the subtype. For information about supported types and for controlling the conversion, see Supported Image Data Subtypes.To control the conversion of your image data or to override the type of conversion based on the subtype, specify additional arguments to imwrite using a cell array. If you specify an image format argument (fmt), then it overrides the default conversion.For example, the following code convertsimageData to JPEG with compression quality 50 and sends the data to the specifiedurl with Content-Type set to"image/jpeg".body = MessageBody({imageData,'jpg','Quality',50}); req = RequestMessage('put',ContentTypeField('image/jpeg'),body); resp = req.send(url);
application/xmltext/xml If Data is an XML DOM in the form of a Java® org.w3c.dom.Document object, MATLAB converts it using thexmlwrite function.IfData is a string or character vector, MATLAB converts it to uint8 using the specified charset. If not specified, the default charset value is UTF-8.
application/x-www-form-urlencoded If Data is a vector ofmatlab.net.QueryParameter objects, then MATLAB converts it to a URL-encoded string. If it is a string or character vector, it is left unchanged.
audio/* Data must be audio data in a form acceptable to the audiowrite function. Create a cell array containing an m-by-n matrix of audio data and a sampling rate in Hz. You can specify additional arguments to audiowrite by adding name-value pair arguments to the cell array.MATLAB supports the following audio types:audio/x-wavaudio/wavaudio/mp4audio/vnd.wavapplication/oggaudio/flac
application/csvtext/csvapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheetapplication/vnd.ms-excel Data must be a table in a form suitable for the writetable function.For csv subtypes, MATLAB converts Data to comma-delimited text using the specified charset. The default charset is US-ASCII.For the other types, MATLAB converts Data to Excel® spreadsheet data.To specify additional name-value pair arguments towritetable, create a cell array containing Data and the additional arguments. If you specify a 'FileType' argument, that type must be consistent with the subtype you specify.

Content-Type Not Specified

If you do not specify a Content-Type field in the request message, MATLAB assigns the type, subtype, and charset based on the type of theData property. This assumed behavior might not result in the Content-Type you intended, or might fail to determine the type, so for best results, specify the Content-Type. The following table describes the assumed Content-Type based on Data. Types not listed might be handled, but the behavior for unlisted types is not guaranteed to remain the same in future releases.

MessageBody.Data Property Type Content-Type Not Specified Resulting Content-Type
stringcharacter arraycell array of character vectors text/plain
table text/csv
cell vector whose first element is a table text/csv — IfFileType is csv, then there is a name,value pair in the vector with the value'FileType','csv' or there is no such pair.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — If FileType isspreadsheet.
org.w3c.dom.Document application/xml
uint8 vector To send a uint8 vector without conversion and ignoring the Content-Type header field, set the Payload property instead ofData.To send character-based data with no conversion, use theunicode2native function. This function uses the charset attribute to convertData to a uint8 vector.

If the type is not one of those listed in the table, then MATLAB determines whether it is one of the following character-based types:

MATLAB converts these types to a string, using the charset, if specified, or US-ASCII for text/plain, UTF-8 for the application types, and the default MATLAB encoding for the other types.

Converting Data in Response Messages

When receiving a message with a payload, MATLAB converts the incoming byte stream (MessageBody.Data property) to an appropriate MATLAB type.

The following table is a list of the Content-Types that MATLAB recognizes in a response message, based the type/subtype properties and the charset attribute in the received Content-Type field. MATLAB converts the data only if theHTTPOptions.ConvertResponse property is true, which is the default. In the table, the asterisk character (*) means any characters.

Response Message Content-Type MATLAB Type in MessageBody.Data Property
application/json Data is converted to a string based on the charset and then to MATLAB data using the jsondecode function.
image/* Data is converted to an image using the imread function with the specified subtype as the format, using default arguments. Ifimread returns more than one value, then Data is a cell array.For the supported types of image data, see Supported Image Data Subtypes. If the subtype is not in this list, then the subtype is passed toimwrite as the format, which might or might not be supported.
audio/* Data is converted using theaudioread function to a cell array of two values, an m-by-n matrix of audio data and a sampling rate in Hz. The subtype determines the format used byaudioread. The supported types are:audio/wavaudio/x-wavaudio/vnd.wavaudio/mp4audio/flacapplication/ogg is not converted because ogg data does not necessarily contain audio only.
text/csv text/comma-separated-values application/csv application/comma-separated-values Data is converted to a table usingreadtable, with assumed'FileType' of csv and charset, if specified, or the MATLAB default encoding.
application/*spreadsheet* Data is converted to a table usingreadtable, with'FileType' assumed to be'spreadsheet'.
text/xml application/xml If Java is available, Data is converted to a Java org.w3c.dom.Document using thexmlread function.If Java is not available, Data is processed as text/plain with theUTF-8 charset.

If the type is not one of those listed in the table, then MATLAB determines whether it is one of the following character-based types:

MATLAB converts these types to a string, using the charset, if specified, orUS-ASCII for text/plain, UTF-8 for the application types, and the default MATLAB encoding for the other types.

If MATLAB does not support the type, or if theHTTPOptions.ConvertResponse property is set tofalse, then:

If conversion of incoming data is attempted but fails (for example,"image/jpeg" data is not valid JPEG data), then the History property in theHTTPException thrown by the RequestMessage.send method contains the ResponseMessage with thePayload property set to the uint8 payload and, if the type is character-based, then Data is set to the payload converted to a string.

Supported Image Data Subtypes

The following subtypes are supported by the imwrite function as the specified format. For example, the format argument for subtypebmp is 'bmp'. Theimread function converts the data with the specified subtype as the format.

Subtype Format Used by imwrite andimread
bmp 'bmp'
gif 'gif'
jpeg 'jpeg'
jp2 'jp2'
jpx 'jpx'
png 'png'
tiff 'tiff'
x-hdf 'hdf'
x-portable-bitmap 'pbm'
x-pcx 'pcx'
x-portable-graymap 'pgm'
x-portable-anymap 'pnm'
x-portable-pixmap 'ppm'
x-cmu-raster 'ras'
x-xwd 'xwd'

See Also

MessageBody | RequestMessage | ResponseMessage | ContentTypeField | HTTPException | HTTPOptions | imwrite | imread | audiowrite | audioread | jsonencode | jsondecode | xmlwrite | xmlread