eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'HTTPInterface':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: HTTPInterface

Inheritance:

   Object
   |
   +--HTTPInterface
Package:
stx:goodies/communication
Category:
Net-Communication-HTTP-Client
Version:
rev: 1.415 date: 2024/04/22 17:42:11
user: stefan
file: HTTPInterface.st directory: goodies/communication
module: stx stc-classLibrary: communication

Description:


An HTTP interface (i.e. a client) which is able to fetch documents using
HTTP GET, HEAD and POST commands.

- can use HTTP 0.9, HTTP 1.0 or HTTP 1.1 (default)
    HTTP 1.1 is defined in RFC2068.

- keeps track of open socket connections and can keep busy connections open.

- long contents (with configurable size limit) are stored into a temporary file
  and the fileName is provided instead of the contents.
  This is useful if huge files are to be transferred.

- define a proxy by answering to HTTPProxyQuery with an instance of HTTPProxySettings.
  (or use the withProxy:do: entry)

Caveat:
    I cannot guarantee that all HTTP 1.1 features are correctly implemented (as usual).
    However, it seems to work for our applications.



[class variables:]
    USEREL0_9                               - if true, HTTP 0.9 protocol is used
    USEREL1_0                               - if true, HTTP 1.0 protocol is used
                                              if both are false, HTTP 1.1 is used.

    Logging                                 - if true, protocol info is sent to Transcript

    TransferInformationSignal               - raised to pass transfer information; param is ASCII text telling
                                              caller what is currently been done (connecting etc.)
                                              Can be used by GUI to show connection state.

    TransferProgressNotificationSignal      - raised to pass transfer information; param is percentage of xferred data
                                              Can be used by GUI to show progress info.

    UnsupportedOperationNotificationSignal  - HTTP server does not support operation
    ContentTypeInformationSignal            - content-type of document as about to be xferred.
    WrongContentTypeNotificationSignal      - content of document is not as specified in allowedMimeTypes arg.
                                              If proceeded, the document is xferred as usual.
    TransferTimeoutNotificationSignal       - xfer timeout
    ShortTransferNotificationSignal         - short document
    CookieStoreRequestSignal                - HTTP server wants to install a cookie

    DefaultTransferTimeout                  - various defaults
    KeepAliveConnections
    MaxNumberOfKeptConnections


copyright
COPYRIGHT (c) 2000 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

Signal constants
o  contentTypeInformationSignal

o  cookieStoreRequestSignal

o  shortTransferNotificationSignal

o  transferInformationSignal

o  transferProgressNotificationSignal

o  transferTimeoutNotificationSignal

o  unsupportedOperationNotificationSignal

o  wrongContentTypeNotificationSignal

debugging
o  logging: aBoolean
enable/disable logging

Usage example(s): 

     self logging:true
     self logging:false

defaults
o  defaultConnectTimeout
return the default connect timeout

Usage example(s): 

     HTTPInterface defaultConnectTimeout
     HTTPInterface defaultConnectTimeout:120
     HTTPInterface defaultConnectTimeout:30

o  defaultConnectTimeout: seconds
set the default connect timeout

Usage example(s): 

     HTTPInterface defaultConnectTimeout
     HTTPInterface defaultConnectTimeout:120
     HTTPInterface defaultConnectTimeout:30

o  defaultTransferTimeout
return the default transfer timeout;
that is the max. time from request to data xmission start

Usage example(s): 

     HTTPInterface defaultTransferTimeout
     HTTPInterface defaultTransferTimeout:120
     HTTPInterface defaultTransferTimeout:30

o  defaultTransferTimeout: seconds
set the default transfer timeout;
that is the max. time from request to data xmission start

Usage example(s): 

     HTTPInterface defaultTransferTimeout
     HTTPInterface defaultTransferTimeout:120
     HTTPInterface defaultTransferTimeout:30

o  maxContentsLengthForDirectData
if a files size is smaller than the value returned by this method, then a bytearray-buffer
is used for the data; otherwise, the data is stored in a temporary file and
the dataFile is passed in the response object.

o  maxNumberOfKeptConnections
return the max. number of kept connections

o  maxNumberOfKeptConnections: numKept
set the max. number of kept connections

Usage example(s): 

     self maxNumberOfKeptConnections
     self maxNumberOfKeptConnections:3
     self maxNumberOfKeptConnections:1

initialization
o  closeKeptConnections
close and flush all kept alive connections

o  initialize
for now, simulate a Mozilla;

Usage example(s): 

     HTTPInterface initialize

instance creation
o  connectTo: anUrlorUrlString
create an instance to myself and connect it to anUrlorUrlString

o  connectTo: hostName port: portNrOrNil
create an instance to myself and connect it to portNr on hostName.
If portNr is nil, the default http port will be used.

Usage example(s): 

     |h|

     h := HTTPInterface connectTo:'www.exept.de' port:nil.
     Transcript showCR:(h requestGET:'/').
     h destroy.

Usage example(s): 

     |h|

     h := HTTPInterface connectTo:'www.exept.de' port:33333.        'should not exist'.
     Transcript showCR:(h requestGET:'/') .
     h destroy.

Usage example(s): 

     |h|

     h := HTTPInterface connectTo:'bla.nowhere' port:nil.
     Transcript showCR:(h requestGET:'/') .
     h destroy.

o  connectTo: hostName port: portNrOrNil useSSL: useSSL
create an instance to myself and connect it to portNr on hostName.
If portNr is nil, the default http port will be used.

Usage example(s): 

     |h|

     h := HTTPInterface connectTo:'www.exept.de' port:nil.
     Transcript showCR:(h requestGET:'/').
     h destroy.

Usage example(s): 

     |h|

     h := HTTPInterface connectTo:'www.exept.de' port:33333.        'should not exist'.
     Transcript showCR:(h requestGET:'/') .
     h destroy.

Usage example(s): 

     |h|

     h := HTTPInterface connectTo:'bla.nowhere' port:nil.
     Transcript showCR:(h requestGET:'/') .
     h destroy.

o  connectTo: hostName port: portNrOrNil useSSL: sslRequested sslVersion: sslVersionOrNil sslSuite: aSSLCipherSuiteOrNil
create an instance to myself and connect it to portNr on hostName.
If portNr is nil, the default http port will be used.

Usage example(s): 

     |h|

     h := HTTPInterface connectTo:'www.exept.de' port:nil.
     Transcript showCR:(h requestGET:'/').
     h destroy.

Usage example(s): 

     |h|

     h := HTTPInterface connectTo:'www.exept.de' port:33333.        'should not exist'.
     Transcript showCR:(h requestGET:'/') .
     h destroy.

Usage example(s): 

     |h|

     h := HTTPInterface connectTo:'bla.nowhere' port:nil.
     Transcript showCR:(h requestGET:'/') .
     h destroy.

o  connectToHost: host port: port viaProxy: httpProxySettings
connect a socket via a proxy.
Answer the connected socket.
THis is not HTTP specific. You can use this socket to connect to any service through a tunnel.
(Although it has to be allowed by the proxy - e.g. in Apache:'AllowCONNECT 443 5222'

Usage example(s): 

        |proxySettings|

        proxySettings := HTTPProxySettings useHost:'exeptn' port:8088 user:'proxyuser' password:'password'.
        self connectToHost:'xmpp.exept.de' port:5222 viaProxy:proxySettings

        |proxySettings|

        proxySettings := HTTPProxySettings useHost:'exeptn' port:8088.
        self connectToHost:'xmpp.exept.de' port:5222 viaProxy:proxySettings

o  new
(comment from inherited method)
return an instance of myself without indexed variables

private helpers
o  composeUrlFrom: urlOrPathArgOrNil host: hostOrNil port: portNrOrNil
create an URL from the arguments.
host and port args (if not nil) take precedence over the parameters
passed in urlOrPathArgOrNil

Usage example(s): 

        self composeUrlFrom:'http://exept.de/path1/path2' host:nil port:nil.
        self composeUrlFrom:'http://exept.de/path1/path2' host:nil port:443.
        self composeUrlFrom:'http://ignored.de/path1/path2' host:'exept.de' port:443.
        self composeUrlFrom:'path1/path2' host:'exept.de' port:443.

o  extractCharSetEncodingFromContentType: arg

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  extractMimeTypeFromContentType: arg

o  generateFieldDataFrom: nameValueAssociations
helper
generates an url parameter string of the form &key1=value1&key2=value2
from the given dictionary

o  logInfo: msg
Logging := false
Logging := true

o  logVerboseInfo: msg
Verbose := false
Verbose := true

o  multiPartBoundaryPost: url filename: aFilename fileNameFieldName: aFilenameFieldName contents: contents otherValues: aValueDict
a post request with field values in a smalltalk-friendly form

o  numericReturnCodeForSymbol: aSymbolicHttpReturnCode
given a symbolic error code, return the corresponding HTTP code

Usage example(s): 

     self numericReturnCodeForSymbol:#'NOT_FOUND' -> 404
     self symbolForReturnCode:404 -> #'NOT_FOUND'

o  processRedirects: countOrNil for: anUrl with: fetchBlock
utility:
evaluate fetchBlock with anUrl, if error, raise it.
If moved, get the moved document;
answer the response.
if countOrNil is nil, a default max redirect chain length of 10 is followed

o  putAcceptString: aStringOrCollection for: what on: aStream
self putAcceptString:nil for:'Accept-Encoding' on:Transcript
self putAcceptString:'gzip' for:'Accept-Encoding' on:Transcript
self putAcceptString:#('gzip') for:'Accept-Encoding' on:Transcript
self putAcceptString:#('gzip' 'tar' 'bzip') for:'Accept-Encoding' on:Transcript

o  request: getOrPost url: urlOrPathOrNil fromHost: hostOrNil port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: user password: passwd
Modified (format): / 08-02-2019 / 15:16:56 / Claus Gittinger

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  symbolForReturnCode: aNumericHttpReturnCode

o  transferRateStringFor: bytesTransferedPerSecond

request API
o  delete: url
a delete request. Usually only useful against a Rest service.
returns a response object

Usage example(s): 

      HTTPInterface
        delete:'http://someURL'.

o  delete: url userName: aUserName password: aPassword
a delete request. Usually only useful against a Rest service.
returns a response object

o  head: url accept: acceptedMimeTypes
get a documents head (i.e. without body) url from host.
Returns a response-object.

Usage example(s): 

      HTTPInterface
        head:'http://www.exept.de/'
        accept:#('image/gif' 'image/xbm' 'text/html')

      HTTPInterface
        head:'http://www.google.de/'
        accept:#('image/gif')

o  head: urlOrPath fromHost: host port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: user password: passwd cookies: aCollectionOfCookiesOrNil
get a documents head (i.e. without body) url from host.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

Usage example(s): 

     HTTPInterface head:'/' fromHost:'www.exept.de'
                   port:nil accept:#('*') fromDocument:'/'
                   userName:nil password:nil cookies:nil 

     HTTPInterface get:'/' fromHost:'www.exept.de'
                   port:nil accept:#('*') fromDocument:'/'
                   userName:nil password:nil cookies:nil

o  put: url userName: aUserName password: aPassword with: data contentType: mimeTypeOfData
a put request with data;
returns a response object

Usage example(s): 

      HTTPInterface
        put:'http://someURL' with:'someData' contentType:'text/plain'.

      HTTPInterface
        put:'http://someURL' with:'someData' contentType:nil.

o  put: url with: data contentType: mimeTypeOfData
a put request with data;
returns a response object

Usage example(s): 

      HTTPInterface
        put:'http://someURL' with:'someData' contentType:'text/plain'.

      HTTPInterface
        put:'http://someURL' with:'someData' contentType:nil.

o  request: getOrPost url: urlOrPathArgOrNil fromHost: hostOrNil port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: userOrNil password: passwordOrNil contentType: contentType contents: contents
send a get/post request to host.
If urlOrPathArgOrNil is nil, host must be non-nil;
if host is nil, urlOrPathArgOrNil must be non-nil.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  request: getOrPost url: urlOrPathArgOrNil fromHost: hostOrNil port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: userOrNil password: passwordOrNil contentType: contentType contents: contents destinationFile: destinationFilenameOrNil
send a get/post request to host.
If urlOrPathArgOrNil is nil, host must be non-nil;
if host is nil, urlOrPathArgOrNil must be non-nil.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  request: getOrPost url: urlOrPathArgOrNil fromHost: hostOrNil port: portNrOrNil proxy: proxySettingsOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: userOrNil password: passwordOrNil contentType: contentType contents: contents destinationFile: destinationFilenameOrNil
send a get/post request to host.
If urlOrPathArgOrNil is nil, host must be non-nil;
if host is nil, urlOrPathArgOrNil must be non-nil.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  request: getOrPost url: urlOrPathArgOrNil fromHost: hostOrNil port: portNrOrNil proxy: proxySettingsOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: userOrNil password: passwordOrNil cookies: aCollectionOfCookiesOrNil contentType: contentType contents: contents destinationFile: destinationFilenameOrNil
send a get/post request to host.
If urlOrPathArgOrNil is nil, host must be non-nil;
if host is nil, urlOrPathArgOrNil must be non-nil.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  withProxy: proxySettingsOrNil do: aBlock
utility function:
perform the request through the proxy defined in proxySettingsOrNil

Usage example(s): 

     self withProxy:(HTTPProxySettings useHost:'fooBar' port:1234) do:[ HTTPInterface get:'https://www.exept.de' ]

     self withProxy:nil do:[ HTTPInterface get:'https://www.exept.de' ]

o  withProxy: proxySettingsOrNil useSsl: useSsl do: aBlock
utility function:
perform the request through the proxy defined in proxySettingsOrNil
if useSsl is set to true, forces url method https if method is http

Usage example(s): 

     self 
        withProxy:(HTTPProxySettings useHost:'fooBar' port:1234) 
        useSsl:true
        do:[ 
            HTTPInterface get:'http://www.exept.de' 
        ]       

     self 
        withProxy:nil 
        useSsl:false                                                 
        do:[ 
            HTTPInterface get:'http://expeccoalm.exept.de' 
        ]

request API - GET
o  get: url
get url;
returns a response-object

Usage example(s): 

      HTTPInterface get:'http://www.exept.de/'
      HTTPInterface get:'http://foo.bar.baz/'

o  get: url accept: acceptedMimeTypes
get url, accepting types in acceptedMimeTypes.
Returns a response-object.

Usage example(s): 

      HTTPInterface
        get:'http://www.exept.de/'
        accept:#('image/gif' 'image/xbm' 'text/html')

      HTTPInterface
        get:'http://www.google.de/'
        accept:#('image/gif')

o  get: url additionalHeaderLines: additionalHeaderLines
get url;
returns a response-object

Usage example(s): 

      HTTPInterface get:'http://www.exept.de/'
      HTTPInterface get:'http://foo.bar.baz/'

o  get: url destinationFile: destinationFilename
get url;
returns a response-object.
Data is stored in destinationFile

Usage example(s): 

      HTTPInterface get:'http://www.exept.de/'
      HTTPInterface get:'http://foo.bar.baz/'

o  get: url destinationFile: destinationFilename maxCountFollowedMoved: maxCountFollowed
get url;
returns a response-object.
Data is stored in destinationFile.
Follow maxCountFollowed redirects (or the default, if nil)

Usage example(s): 

      HTTPInterface get:'http://www.exept.de/'
      HTTPInterface get:'http://foo.bar.baz/'

o  get: url fromDocument: referrer
get url with referrer;
returns a response-object

Usage example(s): 

      HTTPInterface get:'http://www.exept.de/'
      HTTPInterface get:'http://foo.bar.baz/'

o  get: path fromHost: host
get path from host.
Returns a response-object.

Usage example(s): 

      HTTPInterface
        get:'/'
        fromHost:'www.exept.de'

o  get: path fromHost: host port: portNr
get path from host.
If port is not nil, it is a SmallInteger used instead of the default port.
Returns a response-object.

Usage example(s): 

      HTTPInterface
        get:'/'
        fromHost:'www.exept.de'
        port:8080

o  get: path fromHost: host port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL
get path from host.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  get: path fromHost: host port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL maxCountFollowMoved: maxCountFollowed
get a document from host.
A moved response is followed maxCountFollowed times (to prevent endless repetitions)
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  get: urlOrPath fromHost: host port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: user password: passwd
get url from host.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

Usage example(s): 

     HTTPInterface get:'/' fromHost:'porty'
                   port:nil fromDocument:'http://murks'

o  get: urlOrPath fromHost: host port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: user password: passwd cookies: aCollectionOfCookiesOrNil
get url from host.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

Usage example(s): 

     HTTPInterface get:'/' fromHost:'porty'
                   port:nil fromDocument:'http://murks'

o  get: urlOrPath fromHost: host port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: user password: passwd cookies: aCollectionOfCookiesOrNil maxCountFollowMoved: maxCountFollowed
get url from host.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
If the response is a moved-file response, follow the indirection, but at most maxCountFollowed times.
Returns a response-object.

Usage example(s): 

        (self
            get:'https://www.exept.de'
            fromHost:nil 
            port:nil 
            accept:nil 
            fromDocument:nil 
            userName:nil 
            password:nil
            cookies:nil
            maxCountFollowMoved:3) data

o  get: urlOrPath fromHost: host port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: user password: passwd maxCountFollowMoved: maxCountFollowed
get url from host.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
If the response is a moved-file response, follow the indirection, but at most maxCountFollowed times.
Returns a response-object.

o  get: path fromHost: host port: portNrOrNil fromDocument: documentURL
get path from host.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  get: path fromHost: host port: portNrOrNil fromDocument: documentURL maxCountFollowMoved: maxCountFollowed
get a document from host.
A moved response is followed maxCountFollowed times (to prevent endless repetitions)
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  get: path fromHost: host port: portNrOrNil maxCountFollowMoved: maxCountFollowed
get a document from host.
A moved response is followed maxCountFollowed times (to prevent endless repetitions)
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  get: url port: portNr
get url;
returns a response-object

Usage example(s): 

      HTTPInterface get:'http://www.exept.de/'
      HTTPInterface get:'http://foo.bar.baz/'

o  get: url userName: user password: password
get url;
Returns a response-object.

Usage example(s): 

      HTTPInterface
        get:'http://www.exept.de/'
        userName:'foo'
        password:'bar'

o  get: url with: data
a get request with field values in HTTP-request form (&nameKey=value;).
returns a response-object

o  get: url withFields: nameValueAssociations
a get request with field values.
returns a response-object

o  getFile: url
a get request,
returning the data if present, or else raising an error.

Usage example(s): 

     self getFile:'http://www.exept.de/'
     self getFile:'http://www.google.com/'
     self getFile:'http://webservices.daehosting.com/services/isbnservice.wso?WSDL'

o  getFile: url maxCountFollowMoved: maxCountFollowMoved
a get request,
returning the data if present, or else raising an error.
Follow maxCountFollowed redirects (or the default, if nil)

o  getFile: url userName: aUserName password: aPassword
a get request,
returning the data if present, or else raising an error.

o  getFile: url userName: aUserName password: aPassword maxCountFollowMoved: maxCountFollowed
a get request,
returning the data if present, or else raising an error.
Follow maxCountFollowed redirects (or the default, if nil)

o  getStreamFor: url
a get request,
returning a stream on the data if present, or else raising an error.

Usage example(s): 

     self getStreamFor:'http://www.exept.de/'
     self getStreamFor:'http://www.google.com/'
     self getStreamFor:'http://webservices.daehosting.com/services/isbnservice.wso?WSDL'

request API - POST
o  multiPartBoundaryPost: url fromHost: host port: port userName: userName password: password attributes: aValueDict
a post request with field values in a smalltalk-friendly form;
returns a response object.
If aValueDict contains (#'+++UseTmpFile+++' -> true), do not write the value,
but use a temporary file for the data to be sent. Use this for large data.

o  post: path host: host port: port with: data
a post request with field values in HTTP-request form (&nameKey=value;);
returns a response object

Usage example(s): 

      HTTPInterface
        post:'/m5?a=1&s=USD&t=EUR' 
        host:'se.finance.yahoo.com'
        port:80
        with:'foo=1&bar=2'

o  post: path host: host port: port withFields: nameValueAssociations
returns a response object

Usage example(s): 

      HTTPInterface
        post:'/m5?a=1&s=USD&t=EUR' 
        host:'se.finance.yahoo.com'
        port:80
        withFields:(Dictionary new at:'foo' put:'1'; at:'bar' put:'2'; yourself)

o  post: url userName: aUserName password: aPassword with: data
a post request with field values in HTTP-request form (&nameKey=value;);
returns a response object

o  post: url userName: aUserName password: aPassword with: data contentType: aType
a post request with field values in HTTP-request form (&nameKey=value;);
returns a response object

o  post: url with: data
a post request with field values in HTTP-request form (&nameKey=value;);
returns a response object

Usage example(s): 

      HTTPInterface
        post:'http://se.finance.yahoo.com/m5?a=1&s=USD&t=EUR' with:'foo=1&bar=2'

o  post: url with: data contentType: mimeType
a post request with field values in HTTP-request form (&nameKey=value;);
returns a response object

Usage example(s): 

      HTTPInterface
        post:'http://se.finance.yahoo.com/m5?a=1&s=USD&t=EUR' with:'foo=1&bar=2'

o  post: url withFields: nameValueAssociations
returns a response object

Usage example(s): 

      HTTPInterface
        post:'http://se.finance.yahoo.com/m5?a=1&s=USD&t=EUR' 
        withFields:(Dictionary new at:'foo' put:'1'; at:'bar' put:'2'; yourself)

request API - basic
o  request: getOrPost url: urlOrPathArgOrNil fromHost: hostOrNil port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: userOrNil password: passwordOrNil cookies: aCollectionOfCookiesOrNil contentType: contentType contents: contents destinationFile: destinationFilenameOrNil
send a get/post request to host.
If urlOrPathArgOrNil is nil, host must be non-nil;
if host is nil, urlOrPathArgOrNil must be non-nil.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  request: getOrPost url: urlOrPathArgOrNil fromHost: hostOrNil port: portNrOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: userOrNil password: passwordOrNil cookies: aCollectionOfCookiesOrNil contentType: contentType contents: contents destinationFile: destinationFilenameOrNil additionalHeaderLines: additionalHeaderLines
send a get/post request to host.
If urlOrPathArgOrNil is nil, host must be non-nil;
if host is nil, urlOrPathArgOrNil must be non-nil.
If port is not nil, it is a SmallInteger used instead of the default port.
DocumentUrl may be nil or a String containing the url of the referring document.
Returns a response-object.

o  request: getOrPost url: urlOrPathArgOrNil fromHost: hostOrNil port: portNrOrNil proxy: proxySettingsOrNil accept: acceptedMimeTypes fromDocument: documentURL userName: userOrNil password: passwordOrNil cookies: aCollectionOfCookiesOrNil contentType: contentType contents: contents destinationFile: destinationFilenameOrNil additionalHeaderLines: additionalHeaderLinesOrNil
establish the HTTP connection

validation
o  validateAStringOnW3Org: aString
do not remove, application runs asynchronous"

Usage example(s): 

    self validateAStringOnW3Org:''

Instance protocol:

accessing
o  acceptedCharsets

o  acceptedCharsets: acceptedCharsetsStringOrNil
Modified (format): / 20-01-2019 / 00:40:49 / Claus Gittinger

o  acceptedCharsets: acceptedCharsetsStringOrNil acceptedMimeTypes: acceptedMimeTypesStringOrNil

o  acceptedEncodings

o  acceptedEncodings: acceptedEncodingsString
Modified (format): / 20-01-2019 / 00:39:52 / Claus Gittinger

o  acceptedEncodings: acceptedEncodingsString acceptedLanguages: acceptedLanguagesStringOrNil

o  acceptedLanguages

o  acceptedLanguages: acceptedLanguagesStringOrNil
Modified (format): / 20-01-2019 / 00:40:12 / Claus Gittinger

o  acceptedMimeTypes

o  acceptedMimeTypes: acceptedMimeTypesStringOrNil
Modified (format): / 20-01-2019 / 00:40:58 / Claus Gittinger

o  additionalHeaderLines

o  additionalHeaderLines: aStringCollection
hook to add additional stuff to the header

o  authenticationData

o  authenticationData: aString

o  bindTo: anIpSocketAddress
use anIpSocketAddress as originating IP address

o  clientCertificateChain

o  clientCertificateChain: anArray
Modified (format): / 31-07-2020 / 14:41:22 / Stefan Vogel

o  connectTimeout
the connectionTimeout in seconds

o  connectTimeout: anInteger
set the connectionTimeout in seconds

o  contentType

o  contentType: contentTypeString
Modified (format): / 20-01-2019 / 00:41:43 / Claus Gittinger

o  contents

o  contents: stringOrByteArrayOrNil

o  contents: stringOrByteArrayOrNil contentType: contentTypeString

o  cookies

o  cookies: aCollectionOfCookiesOrNil
the cookies to send

o  destinationFile: aFilename
if given, received data will be stored there, instead of being returned
as string/byteAray. use this for big file transfers

o  host: hostArg port: portArg

o  keepConnection

o  keepConnection: aBoolean
if aBoolean is false, the connection will be closed
after request is finished.
If aBoolean is true, the server determines if the connection
is kept in a connection cache.

o  maxContentsLengthForDirectData: anInteger
if given, that is the maximum size of received data to be returned directly as
ByteArray/String. If the received document is larger, it will be stored into a
tempfile and that file's name is found in the dataFile slot of the response data.
If left undefined, a default value (currently 4Mb) is used as a maximum

o  password

o  password: passwordStringOrNil
Modified (format): / 20-01-2019 / 00:38:52 / Claus Gittinger

o  proxySettings

o  proxySettings: proxySettingsOrNil
Modified (format): / 08-03-2022 / 10:46:02 / cg

o  referer
Notice the misspelling - due to the fact that the misspelling made it into the HTTP standard.
See https://en.wikipedia.org/wiki/HTTP_referer

o  referer: aString
Notice the misspelling - due to the fact that the misspelling made it into the HTTP standard.
See https://en.wikipedia.org/wiki/HTTP_referer

o  referrer
Notice the misspelling below - due to the fact that the misspelling made it into the HTTP standard.
See https://en.wikipedia.org/wiki/HTTP_referer

o  referrer: aString
Notice the misspelling below - due to the fact that the misspelling made it into the HTTP standard.
See https://en.wikipedia.org/wiki/HTTP_referer

o  request: aRequestString

o  scramble: aBoolean
if true, the very first header line will be x-<rnd>,
where <rnd> is a random string of random length.
This should make plain-text attacks on https requests
less feasable as otherwise, they all begin with (the predictable)
get <url> HTTP/1.1<CRNL>
And with the scramble string, there are only 2 characters to predict,
and it will not be known, where the other header strings are found.
However, it is not clear, if all servers like an x- line before the get in
the header; therefore, the default for scrambling is false.

o  socket

o  socket: aSocket

o  sslSuite

o  sslSuite: aSSLCipherSuiteOrNil
Modified (format): / 03-08-2023 / 11:44:42 / Stefan_Vogel

o  sslVersion
the ssl version used (i.e. SSL::SSLProtocolVersion tls12).
If left undefined, the current default version is used

o  sslVersion: anSSLProtocolVersionOrNil
set the ssl version (i.e. SSL::SSLProtocolVersion tls12).
If left undefined, the current default version is used

o  suppressUnicode: aBoolean

o  transferTimeout
the transferTimeout in seconds

o  transferTimeout: seconds
set the transferTimeout in seconds

o  url

o  userAgent

o  userAgent: aString

o  userName

o  userName: userNameStringOrNil
Modified (format): / 20-01-2019 / 00:39:06 / Claus Gittinger

o  userName: userNameStringOrNil password: passwordStringOrNil

o  validateCertificates
answer true, if certificates are validated

o  validateCertificates: aBoolean
if aBoolean == true, raise an error if certificate validation fails

connecting
o  connect
establish the connection, use the parameters stored in
my instance variables.
Try to use a cached socket if one exists to host/port vis schema.

Usage example(s): 

cleanup old closed kept connections

Usage example(s): 

there is an old socket for this connection.
                 Close it if no longer needed.

Usage example(s): 

we are going to re-use the connection, so it is no longer available

Usage example(s): 

     |reply|
     Transcript showCR:(Time millisecondsToRun:[
         |h|

         h := HTTPInterface new 
                connectTo:'exept.de' port:nil
                useSSL:true 
                sslVersion: SSL::SSLProtocolVersion tls11
                sslSuite:SSL::TlsRsaWithAes256CbcSha new.

         reply := h requestGET:'/'.
         h close.
     ]).
     reply inspect.

o  connectTo: anUrl
get the parameters to connect from anURL and do the connect.
If host and port is explicitely set, they have precedence over
the values from anUrl.

o  connectTo: hostName port: portNrOrNil
|h|

h := HTTPInterface new connectTo:'exept.de' port:nil.
Transcript showCR:(h requestGET:'/').
h close.

o  connectTo: hostName port: portNrOrNil useSSL: sslRequested
|h reply|

h := HTTPInterface new connectTo:'www.google.de' port:nil useSSL:true.
reply := h requestGET:'/'.
h close.
reply inspect.

o  connectTo: hostName port: portNrOrNil useSSL: sslRequested sslVersion: sslProtocolVersionOrNil sslSuite: aSSLCipherSuiteOrNil
|reply|
Transcript showCR:(Time millisecondsToRun:[
|h|

h := HTTPInterface new
connectTo:'exept.de' port:nil
useSSL:true
sslVersion: SSL::SSLProtocolVersion tls11
sslSuite:SSL::TlsRsaWithAes256CbcSha new.

reply := h requestGET:'/'.
h close.
]).
reply inspect.

initialization
o  initialize
only relevant, when useSSL is set to true

logging
o  logInfo: arg
marked as obsolete by Stefan Vogel at 31-Mai-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  logVerboseInfo: arg
marked as obsolete by Stefan Vogel at 31-Mai-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **

private-connecting
o  connectViaProxy: httpProxySettings
establish a proxy connection to proxyHost:proxyPort.
Answer the connected socket.

o  establishSocketToHost: connectHost port: connectPort
Establish the basic socket connection.
Resolve the hostname on IPv4 and IPv6 and use the first successfull connection.
Answer the newly connected socket or raise an error.

o  socketHandlingAfterRequestWithResponse: responseArg
cache the connection/socket for future requests.
Whether we do caching, depends on the returned HTTP response

queries
o  dataBufferSize
^ 16384

o  isConnected

release
o  close

o  closeSocket

o  destroy

requests
o  requestDELETE: args url: urlArg
perform an HTTP DELETE-request

o  requestGET: urlArg
HTTPInterface new requestGET:'http://www.exept.de'

o  requestGET: urlArg handlingRedirects: countOrNil
process a GET request, follow redirects up to countOrNil times.
If countOrNil is nil, use a default.

Usage example(s): 

        HTTPInterface new requestGET:'https://www.exept.de' handlingRedirects:nil

o  requestGET: urlArg with: newContentsOrNil
optionally pass contents (as urlParameters)

Usage example(s): 

        HTTPInterface new requestGET:'https://www.exept.de'

o  requestGET: urlArg withFields: keyValueAssociations
optionally pass contents (as urlParameters)

o  requestHEAD: urlArg
HTTPInterface new requestHEAD:'https://www.exept.de'

o  requestPOST: args url: urlArg

o  requestPOST: args url: urlArg maxCountFollowMoved: maxCountFollowed

o  requestPUT: args url: urlArg

requests - basic & helpers
o  authenticationStringForUser: user password: passwd
|s|
s := Base64Coder encode:('ca' , ':' , 'ca').
^ (Base64Coder decode:s) asString

o  basicDoRequest: getOrPostOrWhat withData: postData
Send a request and expect a response.
Returns nil or a response.
PostData is the data to be sent with PUT or POST requests.
It may be nil, a ByteArray, a String or a Stream.

The retrieved data is provided as:
- destinationFile's contents, if a destinationFile was given
- direct data (in response data), if the retrieved data is not too big
- a temporary dataFile, for large files.

o  doRequest: getOrPostOrWhat
the central request functionality is here;
generates the text fot the HTTP request,
and tells basicDoRequest ro perform the transaction.
Finally, I care for the connection (i.e. keep/close etc.)

o  extractTransferParametersFromInfo: info
@Commented by Stefan_Vogel at: 2022-09-20 11:02 Reason:

o  getResponse
self class logInfo:'received: ',line.

o  receiveDocument
post a rangeGet ...

o  request: getOrPostOrDeleteOrWhateverUppercaseHTTPCommand url: urlArg
Place an request for urlArg to the server.
Note: the schema/host/port part of the url must not be changed
after the connection setup.

If not yet connected, establish a connection
via schema (HTTP(S)) to host:port as specified in urlArg.
Do not raise exceptions, answer HTTPResponses instead.

requests - obsolete backward compatibility
o  request: getOrPost url: urlArg acceptedEncodings: acceptedEncodingsArg acceptedLanguages: acceptedLanguagesArg acceptedCharsets: acceptedCharsetsArg acceptedMimeTypes: acceptedMimeTypesArg additionalHeaderLines: additionalHeaderLinesArg contentType: contentTypeArg contents: contentsArg from: currentURL

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  request: getOrPost url: urlArg acceptedEncodings: acceptedEncodingsArg acceptedLanguages: acceptedLanguagesArg acceptedCharsets: acceptedCharsetsArg acceptedMimeTypes: acceptedMimeTypesArg additionalHeaderLines: additionalHeaderLinesArg contentType: contentTypeArg contents: contentsArg from: refererArg userName: userNameArg password: passwordArg

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  request: getOrPost url: urlArg acceptedEncodings: acceptedEncodingsArg acceptedLanguages: acceptedLanguagesArg acceptedCharsets: acceptedCharsetsArg acceptedMimeTypes: acceptedMimeTypesArg from: refererArg

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  request: getOrPost url: urlArg acceptedEncodings: acceptedEncodingsArg acceptedLanguages: acceptedLanguagesArg acceptedCharsets: acceptedCharsetsArg acceptedMimeTypes: acceptedMimeTypesArg from: refererArg userName: userNameArg password: passwordArg

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  requestGET: url accept: acceptedMimeTypes
Get url.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  requestGET: url accept: acceptedMimeTypes from: currentURL
Get url. If currentUrl is not nil, this is the referer

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  requestGET: url accept: acceptedMimeTypes from: currentURL userName: user password: passwd
Get url. If currentUrl is not nil, this is the referer

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  requestGET: urlArg from: refererString
Get url. If referer is not nil, this is the referer.
Notice the wrong spelling of referer, which made it into the W3C standard;
written this way to make searching easier.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

Private classes:

    HTTPCookie
    HTTPResponse
    KeptSocketInfo
    RequestInformationSignal
    SuppressWebSocketStartProcessing
    TransferProgressNotificationSignal
    TransferTimeoutNotificationSignal
    WebSocketResponse

Examples:


simple fetch (preferred): 
  |rply document|

  rply := HTTPInterface get:'http://www.google.de/'.
  rply isErrorResponse ifFalse:[
      document := rply data inspect.
      HTMLDocumentView openOnText:document.
  ]

  |rply document|

  rply := HTTPInterface get:'https://www.howsmyssl.com/'.
  rply isErrorResponse ifFalse:[
      document := rply data asString.
      HTMLDocumentView openOnText:document.
  ]
simple fetch (preferred): via https (requires the SSL support package to be loaded): 
  |rply document|

  rply := HTTPInterface get:'https://download.exept.de'.
  rply isErrorResponse ifFalse:[
      document := rply data asString.
      HTMLDocumentView openOnText:document.
  ]
old interface: 
  |rply document|

  rply := HTTPInterface get:'/' fromHost:'www.exept.de' port:443.
  rply isErrorResponse ifFalse:[
      document := rply data asString.
      HTMLDocumentView openOnText:document.
  ]
alternative: 
   |h reply|

   h := HTTPInterface connectTo:'https://www.exept.de:443'.
   (h requestGET:'/') inspect.
   h closeSocket.
write data to a temp file: 
   |h reply|

   h := HTTPInterface connectTo:'https://www.exept.de'.
   h maxContentsLengthForDirectData:0.
   reply := h requestGET:'/'.
   reply inspect.
   reply dataStream inspect.
   h closeSocket.
via a proxy: 
  |rply document|

  HTTPInterface 
      withProxy:(HTTPProxySettings useHost:'exeptn.bh.exept.de' port:8088 user:'proxyuser' password:'password')
      do:[
          rply := HTTPInterface get:'https://www.exept.de/'.
      ].
  rply isErrorResponse ifTrue:[
      rply inspect.
  ] ifFalse:[
      document := rply data.
      HTMLDocumentView openOnText:document.
  ].
request a webSocket: 
  |rply webSocket|

  rply := HTTPInterface get:'ws://127.0.0.1:9229/3822cd54-9b67-4d57-bde8-6d4aa91316b2'.
  rply isErrorResponse ifFalse:[
      webSocket := rply socket.
      webSocket inspect.
  ]
Use a client certificate: 
  |key cert http rply document|

  key := Pkcs8Key fromPemStream:'/etc/letsencrypt/live/exept.de-0001/privkey.pem' asFilename readStream.
  cert := X509Certificate fromPemStream:'/etc/letsencrypt/live/exept.de-0001/cert.pem' asFilename readStream.
  cert := X509Certificate fromPemStream:'/etc/letsencrypt/live/exept.de-0001/fullchain.pem' asFilename readStream.

  http := HTTPInterface new
              clientCertificateChain:{cert};
              connectTo:'https://expeccoalm-example.exept.de/' asURL.
  rply := http requestGet:'/'.
  rply isErrorResponse ifFalse:[
      document := rply data asString.
  ]
Use a client certificate: 
  |key cert http rply document|

  key := Pkcs8Key fromPemStream:'/etc/letsencrypt/live/exept.de-0001/privkey.pem' asFilename readStream.
  cert := X509Certificate new
      subjectNameString:'C=DE, O=Exept Software AG, CN=Test';
      issuerNameString:'C=DE, O=Exept Software AG, CN=Test-CA';
      serialNumber:4711;
      signatureAlgorithmNameString:#sha256WithRSAEncryption;
      startValidity:Timestamp now;
      endValidity:(Date today + 365) asTimestamp;
      key:(RSASecretCryptKey generateKeyLength:2048 publicExponent:65537 rng:RandomGenerator new);
      signSelf;
      yourself.

  http := HTTPInterface new
              clientCertificateChain:{cert};
              connectTo:'https://expeccoalm-example.exept.de/' asURL.
  rply := http requestGet:'/'.
  rply isErrorResponse ifFalse:[
      document := rply data asString.
  ]

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 21 Dec 2024 16:25:40 GMT