www.gusucode.com > external 工具箱matlab源码程序 > external/interfaces/webservices/restful/weboptions.m
%WEBOPTIONS Specify parameters for RESTful web service
%
% Syntax
% ------
% OPTIONS = WEBOPTIONS
% OPTIONS = WEBOPTIONS(Name,Value)
%
% Description
% -----------
% OPTIONS = WEBOPTIONS constructs a default WEBOPTIONS object to specify
% parameters for obtaining data from a web server.
%
% OPTIONS = WEBOPTIONS(Name,Value) returns OPTIONS with the named
% parameters initialized with the specified values. For each Name that
% matches a property name of the WEBOPTIONS class (CharacterEncoding,
% UserAgent, Timeout, Username, Password, KeyName, KeyValue, ContentType,
% or ContentReader) the corresponding Value is copied to the property.
% The size of OPTIONS is scalar. WEBOPTIONS issues an error if Name does
% not match a property name.
%
% WEBOPTIONS properties:
% CharacterEncoding - Character encoding
% UserAgent - User agent identification
% Timeout - Connection timeout
% Username - User identifier
% Password - User authentication password
% KeyName - Name of key
% KeyValue - Value of key
% HeaderFields - Names and values of additional header fields
% ContentType - Type of content
% ContentReader - Content reader
% MediaType - Media representation of POST data
% RequestMethod - Name of HTTP request method
% Arrayformat - format to use when QueryValue is an array
% CertificateFilename - filename of root certificates in PEM format
%
%
% % Example 1
% % ---------
% % Construct a default WEBOPTIONS object and set Timeout value to
% % Inf to indicate no timeout.
% options = weboptions;
% options.Timeout = Inf
%
% % Example 2
% % ---------
% % Construct a WEBOPTIONS object and set Username and Password.
% % When displaying the object, Password is displayed with '*' values.
% % For added security, use inputdlg to prompt for the values.
% values = inputdlg({'Username:', 'Password:'});
% options = weboptions('Username',values{1},'Password',values{2})
%
% % Example 3
% % ---------
% % Construct a WEBOPTIONS object and set the value of ContentReader
% % to a function handle for the importdata function. This may be
% % helpful when reading certain text or CSV files.
% options = weboptions('ContentReader', @importdata)
%
% See also WEBREAD, WEBWRITE, WEBSAVE
% Copyright 2014-2016 The MathWorks, Inc.
classdef weboptions < matlab.mixin.CustomDisplay
properties (AbortSet)
%CharacterEncoding Character encoding
%
% CharacterEncoding is a string indicating the desired character
% encoding of text content. Common values include 'US-ASCII',
% 'UTF-8', 'latin1', 'Shift_JIS', or 'ISO-8859-1'. The default
% value is 'auto' indicating encoding is determined
% automatically.
CharacterEncoding = 'auto'
%UserAgent User agent identification
%
% UserAgent is a string indicating the client user agent
% identification. The default value is ['MATLAB ' version].
UserAgent = ['MATLAB ' version]
%Timeout Connection timeout
%
% Timeout is a positive numeric scalar indicating the connection
% timeout duration in seconds. The Timeout value determines when
% the function errors rather than continuing to wait for the
% server to respond or send data. Set the value to Inf to disable
% timeouts. The default value is 5 seconds.
Timeout = 5
%Username User identifier
%
% Username is a string identifying the user. If you set the
% Username property value, you should also set the Password
% property value. Basic HTTP authentication is utilized. The
% default value is the empty string.
Username = ''
%Password User authentication password
%
% Password is a string indicating the user authentication
% password. If you set the Password property value, you should
% also set the Username property value. If you display the object
% with the Password property set, the value is displayed with
% values of '*'. The actual value is obtained when you get the
% property's value. Basic HTTP authentication is utilized. The
% default value is the empty string.
Password = ''
%KeyName Name of key
%
% KeyName is a string indicating an additional name, such as a
% web service API key name, to add to the HTTP request header. If
% you set the KeyName property value, you should also set the
% KeyValue property value. The default value is the empty string.
%
% To add more than one request header, use the HeaderFields property.
%
% See also KeyValue, HeaderName
KeyName = ''
%KeyValue Value of key
%
% KeyValue is a string, numeric, or logical indicating the value
% of the key, specified by KeyName, to add to the HTTP request
% header. If you set the KeyValue property value, you should also
% set the KeyName property value. The default value is the empty
% string.
%
% See also KeyValue
KeyValue = ''
%ContentType Type of content
%
% ContentType is a string indicating the type of content to
% return. Permissible values are listed in the table below:
%
% Value Description
% ----- -----------
% 'text' string for text/plain, text/html, text/xml, and
% application/xml content
%
% 'image' numeric or logical matrix for image/format content
%
% 'audio' numeric matrix for audio/format content
%
% 'binary' uint8 column vector for binary (non-string) content
%
% 'table' scalar table object for spreadsheet and CSV
% (text/csv) content
%
% 'json' char, numeric, logical, structure, or cell array,
% for application/json content
%
% 'xmldom' Java Document Object Model (DOM) node for text/xml
% or application/xml content. If not specified, XML
% content is returned as a string.
%
% 'raw' Dependent on content type: 'text', 'xmldom', and
% 'json' content are returned as a char column vector,
% all others are returned as a uint8 column vector.
%
% 'auto' Automatically determined based on content type
% and is the default value.
ContentType = 'auto'
%ContentReader Content reader
%
% ContentReader is a function handle used to read content. When
% used with the function webread, the data is downloaded to a
% temporary file and read using the specified function. The
% temporary file is automatically deleted after the data is read
% from the file. The function is passed the temporary filename as
% the first argument. You may be able to use an anonymous
% function to adapt a file-reading function that requires
% additional input arguments. ContentType is ignored when using
% ContentReader.
ContentReader = []
%MediaType Media representation of POST data
%
% MediaType is a string indicating the media representation of
% the content to post to a web service. The default value
% is 'application/x-www-form-urlencoded', indicating a form
% encoded string. For a complete list of values, refer to <a href="matlab:web('http://www.iana.org/assignments/media-types/media-types.xhtml') ">Internet media types.</a>
% The value is not validated against this list of media types.
MediaType = 'application/x-www-form-urlencoded'
%RequestMethod Name of HTTP request method
%
% RequestMethod is a case-insensitive string indicating the HTTP
% method of the request. Permissible values are 'get', indicating
% the HTTP GET method, 'post' indicating the HTTP POST method, or
% 'auto' indicating the method is determined automatically. The
% functions WEBREAD and WEBSAVE use the GET method when the value
% is 'auto'. The function WEBWRITE uses the POST method when the
% value is 'auto'. The default value is 'auto'. The value can be
% abbreviated.
RequestMethod = 'auto'
%ArrayFormat Method used to convert array query values
%
% ArrayFormat controls the format used to convert query values that
% represent multiple values (e.g., vectors or cell arrays) in the URL.
% It is a string with one of the following values:
%
% ArrayFormat Example where queryName='parm' and queryValue=[1,2,3]
% 'csv' parm=1,2,3 (default)
% 'json' parm=[1,2,3]
% 'repeating' parm=1&parm=2&parm=3
% 'php' parm[]=1&parm[]=2&parm[]=3
%
% A query value is considered to contain multiple values if it is:
% a non-scalar number, logical or datetime (each element is a value)
% a character matrix with more than one row (each row is a string value)
% a cell vector (each element is a value)
% Except for character matrices. arrays of more than one dimension are
% not supported. In cell arrays, each element must be a scalar or
% character vector.
ArrayFormat = 'csv'
%HeaderFields Names and values of additional header fields
%
% HeaderFields is an m-by-2 cell array of character vectors specifying the
% names and values of additional header fields to add to the HTTP request
% header. HeaderFields{i,1} is the name of a field and HeaderFields{i,2}
% is its value.
%
HeaderFields = []
%CertificateFilename File name of root certificates in PEM format
%
% CertificateFilename is a character vector or string denoting the location
% of a file containing certificates in PEM format. The location must be in
% the current directory, in a directory on the MATLAB path, or a full or
% relative path to a file. If this property is set and you request an HTTPS
% connection, the certificate from the server is validated against the
% certification authority certificates in the specified PEM file. This is
% used by standard https mechanisms to validate the signature on the
% server's certificate and the entire certificate chain. A connection is
% not allowed if verification fails.
%
% By default, the property value is set to the certificate file that ships with
% MATLAB, located at:
% fullfile(matlabroot,'sys','certificates','ca','rootcerts.pem')
% If you need additional certificates, you can copy this file and add your
% certificates to it. MATLAB provides no tools for managing certificates or
% certificate files, but there are various third party tools that can do so
% using PEM files. PEM files are ASCII files and can be simply
% concatenated. Since security of HTTPS connections depend on integrity of
% this file, you should protect it appropriately.
%
% If you specify the value 'default' the above certificate filename will be
% used.
%
% If set to empty, the only verification done for the server certificate is
% that the domain matches the host name of the server and that it has not
% expired: the signature is not validated.
%
% Set this to empty only if you are having trouble establishing a connection
% due to a missing or expired certificate in the default PEM file and you do
% not have any alternative certificates.
CertificateFilename = weboptions.DefaultCertificateFilename
end
properties (Hidden)
Debug = false;
end
properties (Constant, Access=private)
DefaultCertificateFilename = fullfile(matlabroot,'sys','certificates','ca','rootcerts.pem');
end
methods
function options = weboptions(varargin)
%WEBOPTIONS constructor
if nargin ~= 0
% Parse the inputs from varargin, and return a structure.
inputs = parseInputs(options, varargin);
% Set the input values.
options = setInputs(options, inputs);
end
end
%----------------- set methods ------------------------------------
function options = set.CharacterEncoding(options, value)
% Validate and set CharacterEncoding.
defaultValue = 'auto';
if ~strcmp(value, defaultValue)
options.CharacterEncoding = validateCharacterEncoding(value);
else
options.CharacterEncoding = defaultValue;
end
end
function options = set.RequestMethod(options, value)
% Validate and set RequestMethod.
% Undocumented: Accept a matlab.net.http.RequestMethod
if isstring(value)
value = char(value);
elseif isa(value, 'matlab.net.http.RequestMethod')
value = char(value);
end
value = validatestring(value, ...
{'auto','get','post'}, mfilename, 'RequestMethod');
options.RequestMethod = value;
end
%------------------------------------------------------------------
function options = set.UserAgent(options, value)
% Validate and set UserAgent
options.UserAgent = validateStringValue(value, 'UserAgent');
end
%------------------------------------------------------------------
function options = set.Timeout(options, value)
% Validate and set Timeout.
validateattributes(value, {'numeric'}, ...
{'positive', 'scalar', 'nonnan'}, mfilename, 'Timeout');
options.Timeout = value;
end
%------------------------------------------------------------------
function options = set.Username(options, value)
% Validate and set Username.
options.Username = validateStringValue(value, 'Username');
end
%------------------------------------------------------------------
function options = set.Password(options, value)
% Validate and set Password.
options.Password = validateStringValue(value, 'Password');
end
%------------------------------------------------------------------
function options = set.KeyName(options, value)
% Validate and set KeyName.
options.KeyName = validateStringValue(value, 'KeyName');
end
%------------------------------------------------------------------
function options = set.KeyValue(options, value)
% Validate and set KeyValue.
if ~isempty(value)
if isstring(value)
value = char(value);
end
validateattributes(value, {'string', 'char', 'numeric', 'logical'}, ...
{}, mfilename, 'KeyValue')
value = reshape(value, 1, numel(value));
options.KeyValue = value;
else
options.KeyValue = '';
end
end
%------------------------------------------------------------------
function options = set.HeaderFields(options, value)
validateStringMatrix(value);
options.HeaderFields = value;
end
%------------------------------------------------------------------
function options = set.ContentType(options, value)
% Validate and set ContentType.
if isstring(value)
value = char(value);
end
value = validatestring(value, ...
{'text', 'image', 'binary', 'table', 'audio', 'json', ...
'xmldom', 'raw', 'auto'}, mfilename, 'ContentType');
options.ContentType = value;
end
%------------------------------------------------------------------
function options = set.ContentReader(options, value)
% Validate and set ContentReader.
if ~isempty(value)
validateattributes(value, {'function_handle'}, {'scalar'}, ...
mfilename, 'ContentReader')
options.ContentReader = value;
else
options.ContentReader = [];
end
end
%------------------------------------------------------------------
function options = set.MediaType(options, value)
% Validate and set MediaType
options.MediaType = validateNonEmptyStringValue(value, 'MediaType');
end
%------------------------------------------------------------------
function options = set.ArrayFormat(options, value)
% Validate and set ArrayFormat
% Undocumented: allow an ArrayFormat object
if isstring(value)
value = char(value);
elseif isa(value, 'matlab.net.ArrayFormat')
value = char(value);
end
options.ArrayFormat = ...
validatestring(value, {'csv','json','repeating','php'}, ...
mfilename, 'ArrayFormat');
end
%------------------------------------------------------------------
function options = set.CertificateFilename(options, value)
value = validateStringValue(value, 'CertificateFilename');
if strcmpi(value, 'default')
value = options.DefaultCertificateFilename;
end
options.CertificateFilename = value;
end
%------------------------------------------------------------------
function options = set.Debug(options, value)
validateattributes(value, {'logical'}, {'scalar'}, mfilename, 'Debug');
options.Debug = value;
end
end
%-------------------------- Custom display ----------------------------
methods (Access = protected)
function group = getPropertyGroups(options)
% Provide a custom display for the case in which options is scalar
% and Password is non-empty. Override the default display of
% Password to replace each character with '*'.
group = getPropertyGroups@matlab.mixin.CustomDisplay(options);
if isscalar(options)
password = group.PropertyList.Password;
if ~isempty(password)
group.PropertyList.Password = repmat('*', size(password));
end
end
end
end
end
%--------------------------------------------------------------------------
function inputs = parseInputs(options, args)
% Parse the inputs from the args cell array. Set the default values from
% the properties of options. Value validation is not performed by this
% function.
% Construct the inputParser object.
p = inputParser;
% Add parameter names and default values.
props = properties(options);
for k = 1:length(props)
p.addParameter(props{k}, options.(props{k}));
end
p.addParameter('Debug',options.Debug);
% Set the FunctionName and parse the values.
p.FunctionName = mfilename;
p.parse(args{:});
% Return parsed results.
inputs = p.Results;
end
%--------------------------------------------------------------------------
function options = setInputs(options, inputs)
% Assign the input values to options if they differ (to avoid unnecessary
% set validation).
names = fieldnames(inputs);
for k = 1:length(names)
name = names{k};
value = inputs.(name);
try
options.(name) = value;
catch e
throwAsCaller(e);
end
end
end
%--------------------------------------------------------------------------
function value = validateCharacterEncoding(value)
% Validate CharacterEncoding value. Return a string.
if isstring(value)
value = char(value);
end
validateattributes(value, {'char' 'string'}, {'nonempty', 'vector'}, ...
mfilename, 'CharacterEncoding');
% Validate value using native2unicode.
try
native2unicode('a', value);
catch e
if strcmp(e.identifier, 'MATLAB:unicodeconversion:InvalidCharset')
% Create new message to indicate CharacterEncoding and provide
% additional examples.
id = 'MATLAB:webservices:InvalidCharacterEncodingSpecified';
examples = '''US-ASCII'', ''UTF-8'', ''latin1'', ''Shift_JIS'', ''ISO-8859-1''';
msg = message(id, 'CharacterEncoding', value, examples);
e = MException(id, msg.getString());
end
throwAsCaller(e);
end
value = value(:)';
end
%--------------------------------------------------------------------------
function value = validateStringValue(value, name)
% Validate value as a char vector or string. Return a char row vector or return the
% empty string, if value is empty.
if ~isempty(value)
try
if ischar(value)
validateattributes(value, {'char'}, {'vector'}, mfilename, name);
else
validateattributes(value, {'char' 'string'}, {'scalar'}, mfilename, name);
value = char(value);
end
catch e
throwAsCaller(e);
end
value = value(:)';
else
value = '';
end
end
%--------------------------------------------------------------------------
function value = validateNonEmptyStringValue(value, name)
% Validate value as a non-empty char vector or string. Return a char row vector.
try
if isstring(value)
value = char(value);
end
validateattributes(value, {'char' 'string'}, {'nonempty','vector'}, mfilename, name);
catch e
throwAsCaller(e);
end
value = value(:)';
end
%--------------------------------------------------------------------------
function validateStringMatrix(value)
% Validate value as an m-by-2 string matrix or cellstr. Allow empty values but not
% empty names
if ~isempty(value) || ischar(value) % empty char errors out below
if isstring(value) || iscellstr(value)
% validate string or cell array is m-by-2
validateattributes(value, {'string' 'cell'}, {'size', [NaN,2]}, ...
mfilename, 'HeaderFields')
if iscell(value)
% check for empty names in 1st column
tf = any(cellfun(@isempty, value(:,1)));
if ~tf
% check for any cells that aren't row vectors or empty
tf = any(cellfun(@(z)~isrow(z) && ~isempty(z), value(:)));
end
else
% check for empty strings in 1st column
tf = any(value(:,1)=='');
end
if tf
error(message('MATLAB:webservices:ExpectedNonemptyHeader'));
end
else
% not string array or cellstr; always error on type
validateattributes(value, {'cell array of character vectors', 'string'}, ...
{}, mfilename, 'HeaderFields');
end
end
end