| << Prev | - Up - | Next >> |
This chapter enumerates and describes the classes and their accessible methods of the HttpClient package, thus familiarising one with its Application Progamming Interface.
Service is the base class for all the other classes found in this module. Hence, all the other classes (CgiGET, CgiPOST, CgiISINDEX, UrlGET and UrlHEAD) will inherit its public and protected methods. The programmer is advised to use them instead of Service.
HttpClient.service class Service is the base class for all the other classes present within this module. The reason we present it, is to emphasise the methods inherited by the classes which specialise it.
bytesRead bytesRead(?N)
Returns the instantaneous number of bytes N read of the document being transferred.
closeAll closeAll(+Trace)
This method is used when, before the service completeness, its stop is required. There is no need to call it after the service terminated.
If Trace is bound to false, the current communication will be closed and the opened file removed. Else, if Trace is bound to true, the current communication and the opened file will be closed. It throws errCloseCon and errCloseFile exceptions (see Section 2.8.1).
fetchRate fetchRate(?RateTimePair)
Returns the float#int pair representing the rate and the time it was computed, respectively. The rate is computed as an average of the instantaneous rates over the TInterval time interval, in Kbytes/sec. The time is represented in milliseconds since 00:00:00 GMT, Jan. 1, 1970.
getTimeInterval getTimeInterval(?TInterval)
Returns the TInterval (see Section 2.7.1).
init init(+InPrms+HttpReqPrms)
Initialises the class with the given InPrms and HttpReqPrms input parameters. They are entirely described at Section 2.7.1.
service service(+Meth+Uri+Entity?OutPrms?HttpRepPrms?Location<= _)
Opens an HTTP communication session according to the given method Meth and fetches the document specified by the Uri. In the case of gateway GET and gateway ISINDEX HTTP requests, Uri has to contain the encoded queries (i.e. "http://sasa.com?t=skate"). Meth could be one of the strings "GET", "HEAD" or "POST". Entity has to be a list of "name"#"value" strings pairs or any list of bytes, and encoded or not, respectively (see Section 2.3). Location is bound with the exact location of the requested resource, if provided by the peer and different than Uri or with nil, otherwise. All the other classes present in this module specialise this method. The programmer can specialise this class by introducing other Meths.
As output, it returns two records containing both the content of the fetched document, namely OutPrms and the HTTP response headers, namely HttpRepPrms. It throws all the exceptions described in (see Section 2.8).
Note: service method uses connect method of Oz Open.socket class. Hence, it has the main behaviour as the latter one, namely, it blocks the entire Oz system until it succeeds.
For the explanation of all the other method's parameters refer to Section 2.7.
setTimeInterval setTimeInterval(+TInterval)
Sets the TInterval (see Section 2.7.1).
startTemp startTemp
Continues the current communication session from the point stopTemp method temporarily stopped it.
stopTemp stopTemp
Temporarily stops the current communication session. It can be continued by invoking the startTemp method.
HttpClient.cgiGET class HttpClient.cgiGET class is a specialisation of the HttpClient.service class. All the public and protected methods described in Section 2.1 corresponds to this class, too.
HttpClient.cgiGET class provides the programmer with the possibility of retrieving documents over the network, associating the parameters parsing with the gateway GET HTTP requests.
init init(+InPrms+HttpReqPrms)
Initialises the class with the given InPrms and HttpReqPrms input parameters. They are entirely described at Section 2.7.1.
getService getService(+Uri+CgiPairs?OutPrms?HttpRepPrms)
Opens an HTTP communication session associating CgiPairs parameters parsing with the gateway GET HTTP requests and fetches the document specified by the Uri. CgiPairs has to be a list of "name"#"value" strings pairs (e.g. ["Age"#"35" "Occupation"#"research assistant"]).
As output, it returns two records containing both the content of the fetched document, namely OutPrms and the HTTP response headers, namely HttpRepPrms. It throws all the exceptions described in (see Section 2.8).
For the explanation of all the other input and output parameters refer to Section 2.7.
HttpClient.cgiPOST class HttpClient.cgiPOST class is a specialisation of the HttpClient.service class. All the public and protected methods described in Section 2.1 corresponds to this class, too.
HttpClient.cgiPOST class provides the programmer with the possibility of retrieving documents over the network, associating the parameters parsing with the gateway POST HTTP requests.
init init(+InPrms+HttpReqPrms)
Initialises the class with the given InPrms and HttpReqPrms input parameters. They are entirely described at Section 2.7.1.
getService getService(+Uri+CgiPairs?OutPrms?HttpRepPrms)
Opens an HTTP communication session associating CgiPairs parameters parsing with the gateway POST HTTP requests and fetches the document specified by the Uri. CgiPairs may be a list of "name"#"value" strings pairs or a list of bytes. In the latter case the content of CgiPairs will not be encoded in a CGI-like fashion, allowing the upload of arbitrary entity.
As output, it returns two records containing both the content of the fetched document, namely OutPrms and the HTTP response headers, namely HttpRepPrms. It throws all the exceptions described in (see Section 2.8).
For the explanation of all the other input and output parameters refer to Section 2.7.
HttpClient.cgiISINDEX class HttpClient.cgiISINDEX class is a specialisation of the HttpClient.service class. All the public and protected methods described in Section 2.1 corresponds to this class, too.
HttpClient.cgiISINDEX class provides the programmer with the possibility of retrieving documents over the network, associating the parameters parsing with the gateway ISINDEX HTTP requests.
init init(+InPrms+HttpReqPrms)
Initialises the class with the given InPrms and HttpReqPrms input parameters. They are entirely described at Section 2.7.1.
getService getService(+Uri+IndexValue?OutPrms?HttpRepPrms)
Opens an HTTP communication session associating IndexValue parameters parsing with the gateway ISINDEX HTTP requests and fetches the document specified by the Uri. IndexValue has to be a "value" string (e.g. "research assistant").
As output, it returns two records containing both the content of the fetched document, namely OutPrms and the HTTP response headers, namely HttpRepPrms. It throws all the exceptions described in (see Section 2.8).
For the explanation of all the other input and output parameters refer to Section 2.7.
HttpClient.urlGET class HttpClient.urlGET class is a specialisation of the HttpClient.service class. All the public and protected methods described in Section 2.1 corresponds to this class, too.
HttpClient.urlGET class provides the programmer with the possibility of retrieving documents over the network using ordinary GET HTTP requests.
init init(+InPrms+HttpReqPrms)
Initialises the class with the given InPrms and HttpReqPrms input parameters. They are entirely described at Section 2.7.1.
getService getService(+Uri?OutPrms?HttpRepPrms)
Opens an HTTP communication session and fetches the document specified by the Uri.
As output, it returns two records containing both the content of the fetched document, namely OutPrms and the HTTP response headers, namely HttpRepPrms. It throws all the exceptions described in (see Section 2.8.1).
For the entire explanation of the input and output parameters refer to Section 2.7.
HttpClient.urlHEAD class HttpClient.urlHEAD class is a specialisation of the HttpClient.service class. All the public and protected methods described in Section 2.1 corresponds to this class, too.
HttpClient.urlHEAD class provides the programmer with the possibility of retrieving the HTTP response headers of the documents over the network using HEAD HTTP requests.
init init(+InPrms+HttpReqPrms)
Initialises the class with the given InPrms and HttpReqPrms input parameters. They are entirely described at Section 2.7.1.
getService getService(+Uri?OutPrms?HttpRepPrms)
Opens an HTTP communication session and fetches the HTTP response headers of the document specified by the Uri. Thus, the content of the document is not fetched.
As output, it returns the OutPrms record with its sOut feature's field being bound to nil, and the HttpRepPrms record containing the HTTP response headers. It throws all the exceptions described in (see Section 2.8.1).
For the entire explanation of the input and output parameters refer to Section 2.7.
In this section we describe the I/O parameters found in most of the methods presented within this chapter. The other parameters particular to certain methods are described where they occur.
InPrms inPrms(file:+FileName<= uriBased
proxyPort:+ProxyPort<= nil
proxySrv:+ProxyServer<= nil
overwr:+Overwr<= true
tInterval:+TInterval<= 1500
toFile:+ToFile<= true
toStrm:+ToStrm<= false)
InPrms record provides the programmer with a flexible interface. If not bound or not present, its features will be given default values.
FileName is a string containing the path of the file the document will be put in. The file is written while the document is being transferred.
ProxyPort, if provided, will be used as proxy port. It has to be an integer.
ProxyServer, if provided, will be used as proxy server. It has to be a string.
When ToFile is set true, the boolean Overwr will indicate if the document should be overwritten (true) or duplicated (false), if it already exists. When duplicated, the corresponding file name will have the following form: FileName_N, where N represents the Nth duplication of the file.
TInterval is an integer specifying the time interval to be considered when computing the transmission rate (e.g. when sending it along with the time over the RateStrm stream, or when fetchRate method is invoked, see Section 2.1), in milliseconds.
ToFile is a boolean indicating if the document should be saved into a file (true) or not (false).
ToStrm is a boolean indicating if the document should be returned as a byte stream (true) or not (false).
HttpReqPrms httpReqPrms(accept:+Accept<= nil
accept_charset:+Accept_Charset<= nil
accept_encoding:+Accept_Encoding<= nil
accept_language:+Accept_Language<= nil
authorization:+Authorization<= nil
'from':+From<= nil
if_modified_since:+If_Modified_Since<= nil
refer:+Refer<= nil
user_agent:+User_Agent<= nil
allow:+Allow<= nil
content_encoding:+Content_Encoding<= nil
content_language:+Content_Language<= nil
content_type:+Content_Type<= nil
expires:+Expires<= nil
last_modified:+Last_Modified<= nil
link:+Link<= nil
title:+Title<= nil
uri:+URI<= nil
date:+Date<= nil
pragma:+Pragma<= nil)
HttpReqPrms record provides the programmer with the possibility of setting almost all HTTP 1.0 request headers to be used when communicating with the peer. The peer's response depends more or less on their contents. All the fields of this record are strings.
Accept : set of media ranges which are acceptable as a response to the request.
Accept_Charset : set of preferred character sets.
Accept_Encoding : similar to Accept, but referring to content-coding values.
Accept_Language : similar to Accept, but referring to the set of natural languages.
Authorization : authentication information of the user agent.
From : e-mail address of the user who controls the requesting user agent.
If_Modified_Since : date and time, making the document retrieving conditional.
Refer : address (URI) of the resource from which the Request-URI was obtained.
User_Agent : information about the user agent originating the request.
Allow : set of methods supported by the resource identified by the Request-URI.
Content_Encoding : additional content coding that has been applied to the document to be retrieved.
Content_Language : set of natural languages of the intended audience for the enclosed entity.
Content_Length : length of the document to be retrieved.
Content_Type : MIME type (see RFC 2045) of the document to be retrieved.
Expires : date/time after which the entity should be considered stale.
Last_Modified : date and time the document was last modified.
Link : describes a relationship between the entity and some other resource.
Title : title of the entity.
URI : URI by which the Request-URI can be identified.
Date : the date and time the document is built. Its semantics is described in RFC 822.
Pragma : implementation specific directives.
For the entire explanation of the HTTP 1.0 headers refer to RFC 1945.
Uri is a string specifying the URI location of the document to be retrieved (e.g. "http://www.info.ucl.ac.be", "www.yahoo.com" or "file:///usr/stud/john/tutorial.gz").
OutPrms outPrms(rateStrm:?RateStrm
redirect:?Redirect
sizeRead:?SizeRead
sOut:?SOut
status:?Status
time:?Time
file:?FileName)
OutPrms record represents the main output parameter providing the user with useful information regarding the retrieved document. There are some features within OutPrms record which can also be found within InPrms record (see Section 2.7.1), having the same fields if provided by the user or default ones, otherwise. The output parameters without value will be bound to nil.
SOut is bound with a byte stream representing the retrieved document. If toStrm feature of the InPrms record is set false, or when the content of the requested document is not provided by the peer (e.g. when HEAD HTTP request is invoked), SOut will be bound to nil.
RateStrm is bound with a Port stream whose values will have the form of float#int pair representing the rate and the time it was computed, respectively. The rate is computed as an average of the instantaneous rates over the TInterval time interval, in Kbytes/sec. The time is represented in milliseconds since 00:00:00 GMT, Jan. 1, 1970. When the involved service terminates, whether fails or completes, RateStrm will be sent nil.
Redirect is bound with a list of strings containing the URL redirection, provided when the requested document has been temporarily or permanently moved.
Time is an integer and will be bound with the time when the service completes or fails. It is represented in milliseconds since 00:00:00 GMT, Jan. 1, 1970.
Status is a string and represents the HTTP status code given by the peer (e.g. "200" for OK or "301" for Moved Permanently).
SizeRead is an integer which will be bound with the length of the document actually read.
HttpRepPrms httpRepPrms(expires:?Expires
location:?Location
retry_after:?Retry_After
server:?Server
www_authenticate:?WWW_Authenticate
allow:?Allow
content_encoding:?Content_Encoding
content_language:?Content_Language
content_type:?Content_Type
expires:?Expires
last_modified:?Last_Modified
link:?Link
title:?Title
uri:?URI
date:?Date
pragma:?Pragma)
HttpRepPrms record contains the HTTP 1.0 compliant server response headers. Each of its feature corresponds to a header. Before fetching the document, they are bound with the headers provided by the peer or with nil, otherwise. All headers are provided as strings.
Location : the exact location of the resource that was identified by the Request-URI.
Retry_After : date and time or milliseconds, indicating how long the service is expected to be unavailable to the requesting client.
Server : information about the software used by the origin server to handle the request.
WWW_Authenticate : authentication scheme(s) and parameters applicable to the Request-URI.
The others fields left of the record have the same meaning with those of HttpReqPrms record, as described in Section 2.7.1.
The exceptions raised by the methods of the classes present in HttpClient package are atoms.
Exceptions raised by closeAll, service and getService methods of all classes present in this module:
errCloseCon : there was a problem when closing the connection.
errCloseFile : there was a problem when closing the file.
Exceptions raised by service and getService methods of all classes present in this module:
conPremClosed : the socket connection was closed by the peer while still reading it.
errReadSocket : there was a problem when reading the socket.
errOpenCon : there was a problem while trying to open the connection.
errOpenFile : there was a problem while trying to open the file.
errUriChrs : the Uri was not properly provided.
errWriteFile : there was a problem when writing the file.
errWriteSocket : there was a problem when writing the socket.
Exceptions raised by service and getService methods of all classes involved in CGI parameters parsing, namely HttpClient.service, HttpClient.cgiGET, HttpClient.cgiPOST and HttpClient.cgiISINDEX:
errCgiPrms : there is a problem with the CGI parameters.
errLargeCgiPrms : the length of the encoded CGI parameters is greater than 1024 bytes. This is the case of CGI GET method, where the standard introduces this constrain.
| << Prev | - Up - | Next >> |