Class %Net.HttpRequest

class %Net.HttpRequest extends %RegisteredObject

%Net.HttpRequest provides an interface to issue HTTP requests to a web server and read the response. This allows you to interact with other web sites, for example you could issue a request to get a stock quote from another site, then parse the information returned to store the stock value in the local database. This implimentation is designed to the HTTP/1.0 specification RFC 1945 so although it can talk to HTTP/1.1 servers (as they are backward compatible) it can not issue HTTP/1.1 style requests.

In normal use you create a single %Net.HttpRequest object and use it to issue as many requests as you need to the web server, each %Net.HttpRequest object can be thought of as a single instance of an internet browser. On completion of each request it returns a %Net.HttpResponse object in the HttpResponse property. This is used to see the reponse from the web server. Note that when you call Get, Head, Post, or Put it will automatically Reset the %Net.HttpRequest object ready for another request. For example:

	Set httprequest=##class(%Net.HttpRequest).%New()
	Set httprequest.Server="www.intersystems.com"
	Do httprequest.Get("/")
	Do httprequest.HttpResponse.OutputToDevice()
	Do httprequest.Get("/cache/")
	Do httprequest.HttpResponse.OutputToDevice()

In order to send parameters on the URL, i.e. when you see a URL like

http://www.demo.com/page.html?PARAM1=TEST&PARAM2=HELLO

You use the SetParam method to add these parameters one by one. For example to get the index page from Documatic you do:

	Set httprequest=##class(%Net.HttpRequest).%New()
	Set httprequest.Port=1972
	Do httprequest.SetParam("PAGE","INDEX")
	Do httprequest.Get("/csp/docbook/%CSP.Documatic.cls")
	Do httprequest.HttpResponse.OutputToDevice()

Form data can also be sent with this class. This is done by first inserting the form name/value pairs using the InsertFormData. Then the data is Post to the web server, for example something like:

	Do httprequest.InsertFormData("element","value")
	Do httprequest.Post("/cgi-bin/script.CGI")

Inventory

Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
	44	68

Summary

Properties
AcceptGzip	Authorization	ContentCharset	ContentEncoding
ContentLength	ContentType	Date	EntityBody
FollowRedirect	From	HTTPVersion	HttpResponse
Https	IfModifiedSince	Location	NoDefaultContentCharset
OpenTimeout	Params	Password	Port
PostGzip	Pragma	ProxyAuthorization	ProxyHTTPS
ProxyPort	ProxyServer	ProxyTunnel	ReadRawMode
Referer	RequestHeaderCharset	ResponseStream	SSLConfiguration
SSLError	Server	Timeout	UserAgent
Username	WriteRawMode

Methods
%%OIDGet	%AddToSaveSet	%ClassIsLatestVersion	%ClassName
%ConstructClone	%DispatchClassMethod	%DispatchGetModified	%DispatchGetProperty
%DispatchMethod	%DispatchSetModified	%DispatchSetMultidimProperty	%DispatchSetProperty
%Extends	%GetParameter	%IsA	%IsModified
%New	%NormalizeObject	%ObjectModified	%OriginalNamespace
%PackageName	%RemoveFromSaveSet	%SerializeObject	%SetModified
%ValidateObject	AcceptGzipSet	AuthorizationGet	AuthorizationSet
ContentCharsetGet	ContentCharsetSet	ContentEncodingGet	ContentEncodingSet
ContentLengthGet	ContentTypeGet	ContentTypeSet	CountFormData
CountParam	DateGet	DateSet	DeleteCookie
DeleteFormData	DeleteParam	FromGet	FromSet
Get	GetFullCookieList	GetHeader	GetParam
Head	HorologToRFCDateTime	IfModifiedSinceGet	IfModifiedSinceSet
InsertCookie	InsertFormData	InsertParam	IsFormDataDefined
IsParamDefined	LocationSet	NextFormData	NextParam
OutputFormData	OutputHeaders	OutputParams	ParseContent
PortGet	Post	PragmaGet	PragmaSet
ProxyAuthorizationGet	ProxyAuthorizationSet	Put	RefererGet
RefererSet	RemoveHeader	Reset	ReturnHeaders
ReturnParams	Send	ServerGet	ServerSet
SetHeader	SetParam	UserAgentGet	UserAgentSet

Subclasses
%WebStress.HttpRequest

Properties

• property AcceptGzip as %Boolean [ InitialExpression = 1 ];

If true then we report we can accept gzip compressed data to the web server (the default), if false then do not send the header saying we accept gzip data.

• property Authorization as %String [ Calculated ];

Sets/get the 'Authorization:' header field in the Http request.
A user agent that wishes to authenticate itself with a server-- usually, but not necessarily, after receiving a 401 response--may do so by including an Authorization header field with the request. The Authorization field value consists of credentials containing the authentication information of the user agent for the realm of the resource being requested.
This class understands the Basic authentication mechanism and if you set the Username and Password properties then it will send this information suitably encoded to the server with each request. Note that Basic authentication is not secure and sends to username and password over the network in just base64 encoded form.

• property ContentCharset as %String [ Calculated ];

If the ContentType starts with 'text/' then this is the charset to encode the contents with. This is actually specified in the HTTP Content-Type header with something like:
Content-Type: text/html; charset=UTF-8
You must set this property after you set the ContentType or it will overwrite this value.

• property ContentEncoding as %String [ Calculated ];

Sets/gets the 'Content-Encoding:' entity header field in the HTTP request. This acutally referes to the attribute on the EntityBody.

• property ContentLength as %String [ Calculated ];

Read only property that returns the length of the EntityBody. This can also be obtained by looking at 'http.EntityBody.Size' and is only included for consistancy as this is the value written out for the 'Content-Length:' HTTP request entity header.

• property ContentType as %String [ Calculated ];

Sets/gets the 'Content-Type:' entity header field in the HTTP request. If it is not specified and there is an EntityBody then it default to 'text/html'.
Note: This actually gets/sets the attribute 'CONTENT-TYPE' associated with the stream EntityBody rather than setting a Headers.
A Content-Type specifies the media type of the EntityBody data. A Content-Encoding may be used to indicate any additional content coding applied to the type, usually for the purpose of data compression, that is a property of the resource requested. The default for the content encoding is none.

• property Date as %String [ Calculated ];

Sets/get the 'Date:' header field in the HTTP request.
The Date general-header field represents the date and time at which the message was originated, having the same semantics as orig-date in RFC 822. The field value is an HTTP-date. A date should only be included if the message contains an entity body and even then it is optional. An example is
Date: Tue, 15 Nov 1994 08:12:31 GMT

• property EntityBody as %GlobalBinaryStream;

When an Entity-Body is included with a message, the data type of that body is determined via the header fields Content-Type and Content- Encoding. These define a two-layer, ordered encoding model.
This is a stream so to insert into this stream use:
	Do oref.EntityBody.Write("Data into stream")
See %AbstractStream for more information about streams.

• property FollowRedirect as %Boolean;

If true then automatically follow redirection requests from the web server. These are signaled by the HTTP status codes of the form 3xx. The default is true for GET and HEAD methods. Otherwise the default is false.

• property From as %String [ Calculated ];

The From request-header field, if given, should contain an Internet e-mail address for the human user who controls the requesting user agent. The address should be machine-usable, as defined by mailbox in RFC 822 [7] (as updated by RFC 1123 [6]):
From = "From" ":" mailbox
An example is:
From: webmaster@w3.org
This header field may be used for logging purposes and as a means for identifying the source of invalid or unwanted requests. It should not be used as an insecure form of access protection. The interpretation of this field is that the request is being performed on behalf of the person given, who accepts responsibility for the method performed. In particular, robot agents should include this header so that the person responsible for running the robot can be contacted if problems occur on the receiving end.
The Internet e-mail address in this field may be separate from the Internet host which issued the request. For example, when a request is passed through a proxy, the original issuer's address should be used.

• property HTTPVersion as %String [ InitialExpression = "1.1" ];

The HTTP version we should report to the server when making the request. Defaults to '1.1'.

• property HttpResponse as %Net.HttpResponse;

This holds the %Net.HttpResponse object which contains all the data that the web server returned from this http request. If you wish to hold onto this after you make another http request or you close the %Net.HttpRequest object you should do:
	Set response=httprequest.HttpResponse

• property Https as %Boolean;

If not using a proxy server and this is true then it issues a request for an https page rather than the normal http page. This also changes the default Port on the target system to 443 the https port.
If using a proxy server use of https is determined by ProxyHTTPS and Https controls use of a secure SSL connection to the proxy server. In this case the default ProxyPort becomes, 443 the https port.

• property IfModifiedSince as %String [ Calculated ];

The If-Modified-Since request-header field is used with the GET method to make it conditional: if the requested resource has not been modified since the time specified in this field, a copy of the resource will not be returned from the server; instead, a 304 (not modified) response will be returned without any Entity-Body.
If-Modified-Since = "If-Modified-Since" ":" HTTP-date
An example of the field is:
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
The purpose of this feature is to allow efficient updates of cached information with a minimum amount of transaction overhead.

• property Location as %String;

Name of item to retrieve from the web server. This is always an absolute path, so if you wish to retrieve the document that is refered to from the URI 'http://machine/cache/index.html' the Location will be
cache/index.html
All the request methods such as Get take the location as the first parameter to make calling the method easier. Note the location does not contain a leading '/' character as this is implicit.

• property NoDefaultContentCharset as %Boolean [ InitialExpression = 0 ];

If NoDefaultContentCharset = 1 (true), then no charset will be included for a ContentType beginning with "text/" for which the ContentCharset property was not set. Having no charset in the content-type means iso-8859-1 is the charset used for output of the message. The default value of NoDefaultContentCharset is 0.

• property OpenTimeout as %Integer;

If specified is the amount of time we will wait for the TCP/IP connection to open. If not specified then it will default to Timeout value.

• property Params as %String [ MultiDimensional ];

An array of strings containing any query name/value pairs associated with this request. These are added to the request URL when the request is issued.

• property Password as %String;

If the Username and Password are defined then this information will be send using Basic authentication to the web server. If you manually set the Authorization header this property will be ignored.

• property Port as %Integer;

The TCP/IP port number to connect to. This is normally port 80 (the default) unless the web server has been configured to run on an different port.

• property PostGzip as %Boolean [ InitialExpression = 0 ];

If set to true then any data posted to the HTTP server will be gzipped before being sent. You must be sure the remote server can accept gzip data before setting this property.

• property Pragma as %String [ Calculated ];

The Pragma general-header field is used to include implementation- specific directives that may apply to any recipient along the request/response chain. All pragma directives specify optional behavior from the viewpoint of the protocol; however, some systems may require that behavior be consistent with the directives.
Pragma = "Pragma" ":" 1#pragma-directive
pragma-directive = "no-cache" | extension-pragma
extension-pragma = token [ "=" word ]

• property ProxyAuthorization as %String [ Calculated ];

Sets/get the 'Proxy-Authorization:' header field in the Http request.
A user agent that wishes to authenticate itself with a proxy-- usually, but not necessarily, after receiving a 407 response--may do so by including an Proxy-Authorization header field with the request. The Proxy-Authorization field value consists of credentials containing the authentication information of the user agent for the realm of the resource being requested.

• property ProxyHTTPS as %Boolean [ InitialExpression = 0 ];

If using a proxy server and this is true then it issues a request for an https page rather than the normal http page. This allows a proxy server that supports https to support a secure connection from this %Net.HttpRequest class. This also changes the default Port on the target system to 443 the https port. If using a proxy server, use of https is determined by ProxyHTTPS.

• property ProxyPort as %String [ InitialExpression = 8080 ];

The port to connect to the proxy web server on. This is often port 8080 (the default).
You can specify a default proxy server for this namespace or for this Caché by setting ^SYS("HttpRequest","ProxyPort") or ^%SYS("HttpRequest","ProxyPort").

• property ProxyServer as %String;

If you need to request a web page through a proxy server you specify the proxy server host name in this property. If this property is defined then the http request will be directed at this machine and it will forward the request to the machine at Location and return the response.
You can specify a default proxy server for this namespace or for this Caché by setting ^SYS("HttpRequest","ProxyServer") or ^%SYS("HttpRequest","ProxyServer").

• property ProxyTunnel as %Boolean [ InitialExpression = "0" ];

If true then use the HTTP CONNECT command to establish a tunnel through the proxy to the target HTTP server. The address of the proxy server is taken from ProxyServer and ProxyPort. If ProxyHttps is true then once the tunnel is established we will negotiate the SSL connection. The Https property is ignored as the tunnel establishes a direct connection with the target system.

• property ReadRawMode as %Boolean [ InitialExpression = 0 ];

If true then the body of the response will be read in using RAW mode, ie. with no characterset translate. If false (the default) then it will use the charset specified in the response headers.

• property Referer as %String [ Calculated ];

The Referer request-header field allows the client to specify, for the server's benefit, the address (URI) of the resource from which the Request-URI was obtained. This allows a server to generate lists of back-links to resources for interest, logging, optimized caching, etc. It also allows obsolete or mistyped links to be traced for maintenance. The Referer field must not be sent if the Request-URI was obtained from a source that does not have its own URI, such as input from the user keyboard.
Referer = "Referer" ":" ( absoluteURI | relativeURI )
Example:
Referer: http://www.w3.org/hypertext/DataSources/Overview.html
If a partial URI is given, it should be interpreted relative to the Request-URI. The URI must not include a fragment.
Note: that when you call Reset this field is automatically updated with the last request URI, i.e. Location.

• property RequestHeaderCharset as %String [ InitialExpression = "UTF-8" ];

The character set to send the HTTP request header in. According to the RFC the HTTP header should only contain ASCII characters as the behaviour with characters outside this range is unspecified. This class defaults to using UTF-8 as this leaves all the ASCII characters unchanged. You should never need to change this parameter.

• property ResponseStream as %CacheString;

Optional property, if set to a stream then this is the stream that will be used to write the data from the web server to rather than constructing a stream of its own. This allows you to specify which type of stream you wish to read the data into, for example a file stream rather than a global stream which is the default.

• property SSLConfiguration as %String;

The name of the activated TLS/SSL configuration to use for https requests.

• property SSLError as %String;

If request uses an SSL connection and a SSL handshake error has occurred, then SSLError contains text describing the SSL error.

• property Server as %String [ Calculated ];

The IP address or machine name of the web server that you wish to connect to. This defaults to 'localhost', i.e. your current machine if not specified. This also sets the 'Host' http header field.

• property Timeout as %Integer [ InitialExpression = 30 ];

The amount of time to wait for a response from the web server before assuming that the web server is not responding. This defaults to 30 seconds.

• property UserAgent as %String [ Calculated ];

The User-Agent request-header field contains information about the user agent originating the request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring responses to avoid particular user agent limitations. Although it is not required, user agents should include this field with requests. The field can contain multiple product tokens and comments identifying the agent and any subproducts which form a significant part of the user agent. By convention, the product tokens are listed in order of their significance for identifying the application.
User-Agent = "User-Agent" ":" 1*( product | comment )
The default value of this field is:
User-Agent: Mozilla/4.0 (compatible; Cache;)

• property Username as %String;

If the Username and Password are defined then this information will be send using Basic authentication to the web server. If you manually set the Authorization header this property will be ignored.

• property WriteRawMode as %Boolean [ InitialExpression = 0 ];

If true then the body (EntityBody) of the request will be written using RAW mode, ie. with no characterset translate. If false (the default) then it will use the charset specified in the request headers.

Methods

• method AcceptGzipSet(val As %Boolean) as %Status

This is a Set accessor method for the AcceptGzip property.

• method CountFormData(name As %String) as %Integer

Returns the number of values associated with the name-value pair name.

• method CountParam(name As %String) as %Integer

Returns the number of values associated with the name-value pair name.

• method DeleteCookie(name As %String, path As %String, domain As %String) as %Status

Remove a cookie from this %Net.HttpRequest object. The name, path, and domain must match the ones used to insert the cookie in the first place.

• method DeleteFormData(name As %String, index As %Integer = "") as %Boolean

Removes this key from the collection

• method DeleteParam(name As %String, index As %Integer = "") as %Boolean

Removes this key from the collection

• method Get(location As %String = "", test As %Integer = 0, reset As %Boolean = 1) as %Status

Issue the Http 'get' request, this will cause the web server to return the page requested. If this completes correctly the response to this request will be in the HttpResponse. The location is the url to request, e.g. '/test.html'. This can contain parameters which are assumed to be already URL escaped, e.g. '/test.html?PARAM=%25VALUE' sets PARAM to %VALUE. If test is 1 then instead of connecting to a remote machine it will just output what it would have send to the web server to the current device, if test is 2 then it will output the response to the current device after the Get. This can be used to check that it will send what you are expecting. This calls Reset automatically after reading the response, except in test=1 mode or if reset=0.

• method GetFullCookieList(ByRef cookies) as %Integer

Passed cookies by reference and return an array of cookies so you can see which cookies have been set, or persist them into a database if wished. The return from this method is the number of cookies that are in the array. The format of the array is:
array(index)=$LB(name,domain,path,value,expires,secure)

• method GetHeader(name As %String) as %String

Allows you to obtain the current value for any of the Http headers that have been set.

• method GetParam(name As %String, default As %String = "", index As %Integer = 1) as %String

Returns the value of name-value pair name.
If more than one value is associated with name, then the values are subscripted using index starting with 1. index
If the name-value pair is not defined, returns the value of default.

• method Head(location As %String, test As %Integer = 0, reset As %Boolean = 1) as %Status

Issue the Http 'head' request, this will cause the web server to just return the header of the response and none of the body. If this completes correctly the response to this request will be in the HttpResponse. The location is the url to request, e.g. '/test.html'. This can contain parameters which are assumed to be already URL escaped, e.g. '/test.html?PARAM=%25VALUE' sets PARAM to %VALUE. If test is 1 then instead of connecting to a remote machine it will just output what it would have send to the web server to the current device, if test is 2 then it will output the response to the current device after the Head. This can be used to check that it will send what you are expecting. This calls Reset automatically after reading the response, except in test mode or if reset=0.

• classmethod HorologToRFCDateTime(horolog As %String = $Horolog) as %String

Helper function to convert from a $H value into the date/time format suitable for use in an HTTP request. It converts the timezone from the current $H value to the GMT timezone as well as outputting the correct format.

• method InsertCookie(name As %String, value As %String, path As %String, domain As %String, expires As %String, secure As %Boolean = 0) as %Status

Add a cookie to this %Net.HttpRequest object. The name is the name of the cookie, the value is the value this cookie is set to. The path is the path to store the cookie under, it will only be output for this path and any subpaths on the server. The domain is the name of the machine the cookie is downloaded from. Then expires is the date/time when this cookie will expire. The secure parameter is if the cookie should be send over secure channels only, i.e. https.

• method InsertFormData(name As %String, value As %CacheString)

Set the value of name-value pair name to value.
If more than one value is associated with name, then the values are subscripted using index starting with 1. The value inserted can be either a %String or a stream.

• method InsertParam(name As %String, value As %String)

Set the value of name-value pair name to value.
If more than one value is associated with name, then the values are subscripted using index starting with 1.

• method IsFormDataDefined(name As %String, index As %Integer = 1) as %Boolean

Tests if a name-value pair name is defined.

• method IsParamDefined(name As %String, index As %Integer = 1) as %Boolean

Tests if a name-value pair name is defined.

• method NextFormData(name As %String) as %String

Returns the next key in sequence

• method NextParam(name As %String) as %String

Returns the next key in sequence

• method OutputFormData(stream As %Stream.Object, table As %String) as %String

• method OutputHeaders()

Output the full list of Http headers that will be sent to the machine Server for the item Location to the current device. This does not include any entity headers associated with the EntityBody.

• method OutputParams(params As %String = "", table As %String)

Output all the parameters to the current device. The params is any parameters that you wish to be included in the parameters output, these are assumed to already be URL escaped.

• classmethod ParseContent(in As %String, ByRef return As %String) as %Boolean

Parse a name=value,name2="newvalue" type list

• method Post(location As %String = "", test As %Integer = 0, reset As %Boolean = 1) as %Status

Issue the Http 'post' request, this is used to send data to the web server such as the results of a form, or upload a file. If this completes correctly the response to this request will be in the HttpResponse. The location is the url to request, e.g. '/test.html'. This can contain parameters which are assumed to be already URL escaped, e.g. '/test.html?PARAM=%25VALUE' sets PARAM to %VALUE. If test is 1 then instead of connecting to a remote machine it will just output what it would have send to the web server to the current device, if test is 2 then it will output the response to the current device after the Post. This can be used to check that it will send what you are expecting. This calls Reset automatically after reading the response, except in test=1 mode or if reset=0.

• method Put(location As %String = "", test As %Integer = 0, reset As %Boolean = 1) as %Status

Issue the Http 'put' request, this is used to upload data to the web server, it is not used that often. If this completes correctly the response to this request will be in the HttpResponse. The location is the url to request, e.g. '/test.html'. This can contain parameters which are assumed to be already URL escaped, e.g. '/test.html?PARAM=%25VALUE' sets PARAM to %VALUE. If test is 1 then instead of connecting to a remote machine it will just output what it would have send to the web server to the current device, if test is 2 then it will output the response to the current device after the Put. This can be used to check that it will send what you are expecting. This calls Reset automatically after reading the response, except in test=1 mode or if reset=0.

• method RemoveHeader(name As %String) as %Status

Remove a Http header value

• method Reset() as %Status

Reset the %Net.HttpRequest class so that it can issue another request. This is much faster than closing this object and creating a new %Net.HttpRequest object. This also moves the value of Location to Referer. It is called by the Send automatically after issuing a request.

• method ReturnHeaders() as %String

Return the full list of Http headers that will be sent to the machine Server for the item Location. This does not include any entity headers associated with the EntityBody.

• method ReturnParams() as %String

Return the list of parameters that this request will output.

• method Send(type As %String, location As %String, test As %Integer = 0, reset As %Boolean = 1) as %Status

Method that actually sends HTTP request to the server. This is normally called from Get, Post, Put, Head but if you wish to use a different HTTP verb you can call this directly passing the type as the verb you require.

• method SetHeader(name As %String, value As %String) as %Status

Add a header to the http request. Most of the normal headers that you may want are covered by properties of this class such as Date however if you wish to add a non standard header then call this. For example:
	Do httprequest.SetHeader("MyHeader","Data to display")
Note that headers such as Content-Type, Content-Encoding, and Content-Length are part of the entity body rather than the http main headers and as such as forwarded to the ContentType, ContentEncoding and trying to set the Content-Length is just ignored as this is a read only property. Also any attempt to set the 'Connection' header is ignored at this request class does not support persistent connections.

• method SetParam(name As %String, value As %String, index As %Integer = 1)

Set the value of the name-value pair name. The optional index is used to associate multiple value with a single name.


[BASEXML] > [%Net] > [HttpRequest]		Private Storage