libUrlSetLogField empty
   
    

libUrlVersion()

This function returns the current version of the libUrl library. There is no special significance to the numbers, but will be useful for reference when reporting any problems or difficulties.

libUrlLastHttpHeaders()

This returns the headers of the most recent http request, including the request line.

libUrlLastRhHeaders()

This function returns the headers of the most recent reply from a server (remote host) to an http request.

libUrlSetCustomHttpHeaders <headers>

Use this command to set your own custom headers for an http request. The <headers> argument must include the http request line.

Note that this command differs from the httpHeaders property. Header lines included in the httpHeaders property are added in addition to the default headers that are used for http requests. Headers in the httpHeaders property that have the same field title will replace the matching header in the default headers.

Headers set with libUrlSetCustomHttpHeaders will completely replace the request line and header fields used by default requests. This allows you to take complete control of http requests.

The custom headers set with libUrlSetCustomHttpHeaders are reset to empty after each request. So if you are using this command, you must use it before each request.

Lines in the headers argument should be separated by a Revolution/Metacard return character. libUrl will convert returns to crlf before sending the request.

libUrlFtpUploadFile <file>, <url> [, <message>]

libUrlFtpUploadFile uploads data directly from a file on the local drive to an ftp server. This is better for transferring very large files than using "put", which first loads to RAM all the data to be transferred.

The optional message parameter will cause that message to be called when the upload completes (or when an error occurs). Two parameters are passed with the message: the url and its urlStatus. The message should be in the same script as the libUrlFtpUploadFile command.

       on mouseUp
         answer file "Select a file to upload"
         if it is not empty then
          put it into tSourcePath
          set the itemDel to "/"
          put last item of tSourcePath into tFileName
          put "ftp://ftp.xxxxxx.com/uploads/" & tFileName into tUrl
          libUrlFtpUploadFile tSourcePath, tUrl, "loadDone"
         end if
        end mouseUp

        on loadDone pUrl, pStatus
          if pStatus is not "uploaded" then
            answer "Upload failed"
          end if
          unload url pUrl
        end loadDone

libUrlDownloadToFile <url>, <file> [, <message>]

libUrlDownloadToFile downloads data directly to a file on the local machine. This is better for transferring very large files than using "get" or "load", which first load all the data into RAM.

The optional message parameter will cause that message to be called when the upload completes (or when an error occurs). Two parameters are passed with the message: the url and its urlStatus. The message should be in the same script as the libUrlFtpUploadFile command.

       on mouseUp
         ask file "Select a file to save to"
         if it is not empty then
           put it into tDestPath
           put "http://www.xxxxxx.com/stuff/greatstuff.jpg" into tUrl
           libUrlDownloadToFile tUrl, tDestPath, "loadDone"
         end if
        end mouseUp

        on loadDone pUrl, pStatus
          if pStatus is not "cached" then
            answer "Download failed"
          end if
          unload url pUrl
        end loadDone

libUrlSetStatusCallback <message>,<long id of object>

libUrlSetStatusCallback allows you to set a callback message that will be sent during download and upload requests. The message sends status data of any current requests in a similar form to the urlStatus function. However, using a callback allows you to get status data even during blocking calls such as get url. This makes it easier to set up things such as progress bars.

To set the callback message, pass the name of the message and the long id of the object where the message handler resides.

        on mouseUp
         libUrlSetStatusCallback "urlCallback", (the long id of stack "status")
        end mouseUp
  

libUrl will then send the message at the same time as it updates the urlStatus value. It passes two arguments with the message: the url and the current status. So, using the example above, you would set a handler in the stack script of stack "status".

        on urlCallback pUrl, pStatus
         put pStatus into field "status"
        end urlCallback
  

The status argument will contain a string similar to that returned by urlStatus. The only difference that instead of "cached", "downloaded" is passed when a download has completed.

To turn off the callback feature, just send libUrlSetStatusCallback with an empty parameter.

        libUrlSetStatusCallback empty

libUrlSetFtpListCommand <"LIST"|"NLST">

libUrlSetFtpListCommand allows you to switch the ftp command that is sent when getting a directory listing. The choice is LIST or NLST. LIST returns the directory listing in the standard ftp style, which for most ftp servers is the Unix listing style. NLST returns only the file names in a return delimited list. The default is LIST, and passing anything other than NLST as an argument will cause the LIST command to be used.

Note that when using NLST, any sub-directory names are included in the returned data along with filenames.

        libUrlSetFtpListCommand "NLST"

libUrlFtpCommand(<command string>,<host address>[,<username>,<password>])

libUrlFtpCommand allows you to send any ftp command to an ftp server. This is a powerful function that potentially provides full ftp support. However, to use it, you must be familiar with ftp commands and responses.

The <command string> parameter can be any FTP command string. For example, you would pass "PWD" to get the current working directory of the ftp server. The <host address> parameter is the address of the ftp server, for example "ftp.myserver.com" or "192.168.123.4". If the address doesn't include a port number, the standard ftp port (21) will be used. Unless you are connecting to an anonymous account, you should also pass the username and password for the ftp account.

The function returns the server response or an error message if an error occurred. A server response will always begin with a 3-digit code followed by any other relevant information. For example, a typical response to the PWD command would be: 257 "/" is current directory

        put "192.168.123.4" into tHost
        put "testfolder/file_1.cgi" into tFile
        put "dave" into tUser
        put "*****" into tPass##use a real password
        put "SITE CHMOD 755" && tFile into tCmd
        get libUrlFtpCommand(tCmd, tHost,tUser,tPass)
        answer it

libUrlFormData(...)

libUrlFormData formats data in the standard format suitable for sending to form processing CGIs and other processes on a web server. The function accepts variable numbers of parameters and treats them as key-value pairs. The first parameter is the name of the first form part, the second the value of the first part, the third is the name of the second part, and so on.

        put "John" into tName
        put "Hello" into tMessage
        get libUrlFormData("name", tName,"message", tMessage)
        post it to url "http://www.someserver.com/cgi-bin/form.pl"
        

In this case, the data posted to the url will look like this: name=John&message=Hello

libUrlMultipartFormData(<form data>,...)

libUrlMultipartFormData formats data in the way described in rfc 1867. It was designed for posting files to web servers. The function can be called in a number of ways depending on the parameters passed. In all cases, the first parameter must be a variable which will be filled with the form data. The function will return empty if successful, or an error message if it fails (for example, if it couldn't open a file).

Note: When you need to supply a file as the value of a parameter, you must pass the file name preceded by the text "<file>".

Note: In all cases, the first line of the data returned in the form data variable is the Content-Type header that must be included in the httpHeaders of the url request. Lines 2 to the end of the data is the data that must be posted to the url.

The standard way to call the function is with pairs of name/value parameters.

        put empty into tForm
        put "http://www.someserver.com/cgi-bin/form.cgi" into tUrl
        put "dave" into tName
        put "hello" into tMessage
        put "<file>" & "C:/myfile.txt" into tFile
        if libUrlMultipartFormData (tForm, "name", tName, "message", tMessage, "file", tFile) is not empty then
          answer it ##error
        else
          set the httpHeaders to line 1 of tForm
          post line 2 to -1 of tForm to url tUrl 
          ## check the result, etc., here
          set the httpHeaders to empty
        end if
        

You can also pass in an array instead of pairs of parameters. This could be useful if there are many parts to a form. The array must be numerically indexed, and each element should contain the part name and part value, separated by a comma. So (using the above example):

        put empty into tForm
        put "dave" into tName
        put "hello" into tMessage
        put "<file>" & "C:/myfile.txt" into tFile
        put "name," & tName into tArray[1]
        put "message," & tMessage into tArray[2]
        put "file," & tFile into tArray[3]
        if libUrlMultipartFormData(tForm, tArray) is not empty then
         answer it ##error
        else
          set the httpHeaders to line 1 of tForm
          post line 2 to -1 of tForm to url <whatever>
          ## check the result, etc., here
          set the httpHeaders to empty
        end if
        

You can also call the function with no arguments except the form data. This will return an "empty" form. Basically, line 1 is the header, and line 2 is the final boundary mark of the form. It is of no use by itself, but it can be used with libUrlMultipartFormAddPart. See below for an example.

libUrlMultipartFormAddPart(<form data>,<part name>,<value>[,<MIME type>,<encoding>])

This lets you add parts to a multipart form one at a time. It also lets you optionally specify the mime type and transfer encoding for each part. This can be useful where the mime type or transfer encoding has to be specified.

        put empty into tForm
        put "dave" into tName
        put "hello" into tMessage
        if libUrlMultipartFormData (tForm, "name", tName, "message", tMessage) is not empty then
         ##handle error and exit
        end if
        set the httpHeaders to line 1 of tForm
        delete line 1 of tForm
        put "<file>" & "C:/myfile.gif" into tFile
        put "image/gif" into tType
        put "binary" into tEnc
        if libUrlMultipartFormAddPart(tForm,"file", tFile, tType, tEnc) <> empty then
          ##handle error and exit
        else
          post  tForm to url <whatever>
          set the httpHeaders to empty
        end if

libUrlSetAuthCallback <method>,<message>
libUrl_authcb_SetAuthToken <url>,<header string>,<token>,<use again>
libUrl_authcb_Resend <url>

These libUrl messages allow you to set a callback routine for handling authentication with http servers and proxies. Generally, these are enabling routines, and may require use of an external or other scripts when handling certain authentication schemes (for example NTLM or kerberos). libUrl provides support for handling the Basic authentication scheme only. Support for other schemes may be available from third parties.

Use libUrlSetAuthCallback to set a handler to be used for handling a particular authentication scheme. For example, to handle the Basic authentication scheme, you might do this:

      libUrlSetAuthCallback "Basic", "authCallback"

where "authcallback" is the name of a handler. The hander should be in the same script as the handler that calls libUrlSetAuthCallback, or in that object's message path.

You can set callbacks for different Authentication methods. For example, the following two lines would set two handlers to be used for handling Basic and NTLM authentication schemes.

      libUrlSetAuthCallback "Basic", "BasicAuthCallback"
      libUrlSetAuthCallback "NTLM", "NTLMAuthCallback"

The order of setting callbacks matters. Preference is given in the reverse order of the order that schemes are turned on. Where a server supports more than one scheme, the most recently turned on scheme that the server supports will be used.

(Note: To strictly follow the http rfc (2616), the schemes to be used should be turned on in order of weakest to strongest.)

The same callback handler is used for both Proxy and Server authentication. Your callback handler shouldn't have to make a distinction. libUrl will resolve which is being used.

You can stop using a callback by just calling libUrlSetAuthCallback again with an empty message. For example:

      libUrlSetAuthCallback "Basic", ""

When a 407/401 response is detected by libUrl, the received headers are scanned for Proxy-Authenticate/WWW-Authenticate headers. The associated schemes are then matched against the callbacks already registered with libUrlSetAuthCallback. If a match is found, the callback message is sent to the target object (if it exists).

Two arguments are passed to the callback: the originally requested url and the related "authenticate" header received from the server. E.g.

    Proxy-Authenticate: Basic realm="wonderland"

There are some rules for the callback handler. Basically it has to do 5 things:

1. It has to create the appropriate token (credentials) for the server. (A libUrlBasicAuthToken() function that returns a suitable token for Basic schemes is now part of libUrl. An external will be required to provide the token/credentials for NTLM)
   
   The token/credentials must begin with the name of the scheme being used. Essentially, it's the part that appears after the "Proxy-Authorization:" or "Authorization:" field title of the header.


2. It has to "set" the token. Use libUrl_authcb_SetAuthToken to do this. You call it like this:
   

       libUrl_authcb_SetAuthToken <url>, <HeaderString>, <Token>, <UseAgain>

   <url> and <HeaderString> are exactly the same values that were passed into the callback handler. <token> is the token you have just obtained. <UseAgain> is true or false depending whether you want the token to be stored for re-use. With NTLM, you would set this to false, but with Basic or Digest you would typically set it to true. (When set to true, libUrl will automatically set Authorization headers on subsequent requests.)


3. It has to resend the original request. This must be done with the libUrl_authcb_Resend handler. You just pass it the same url that was passed to the callback handler.

       libUrl_authcb_Resend <url>

4. It must return the result of the libUrl_authcb_Resend call. E.g

        libUrl_authcb_Resend pUrl
        return the result

5. It must have an "escape mechanism" if things go wrong. For example, a "Basic" scheme callback might put up a name/password dialog. The user can't remember the password and wants to Cancel. The only way to cleanly escape is to return empty.

Here is an example of a callback handler that handles Basic authentication.

     on authCallback pUrl, pHeaderString
         local tRealm
         put "realm=(" & quote & ".+?" & quote & ")" into tRegEx
         get matchText(pHeaderString, tRegEx,tRealm)
    
         ask "Enter User Name for realm" && tRealm
         if it is empty then return empty
         put it into tName
         ask "Enter password for realm" && tRealm
         if it is empty then return empty
         put it into tPassword

         put libUrlBasicAuthToken(tName,tPassword) into tCredentials
    
         libUrl_authcb_SetAuthToken pUrl, pHeaderString, tCredentials, true
         libUrl_authcb_Resend pUrl
         return the result
     end authCallback

libUrlBasicAuthToken(<name>,<password>)

This function returns the Base64 encoded authorization token needed for the Basic authentication scheme. The following example:

     get libUrlBasicAuthToken("dave","abracadabra")

will return this:

    Basic ZGF2ZTphYnJhY2FkYWJyYQ==

libUrlSetExpect100 <limit>

<limit> is a number of bytes.

When called, subsequent POST requests will add an "Expect: 100-continue" field to the http headers when the data to be posted exceeds the limit. The data won't be written to the socket until a 100 Continue response is received from the server.

This can be useful when posting large amounts of data and where there is a risk of the POST failing (because of failed authentication, or whatever). For example, if authentication is required, the data won't be written until after the authentication has cleared.

libUrlFollowHttpRedirects <true|false> (new in 1.1.1)

When set to true (the default), libUrl will respond to 301, 302, and 307 responses by trying to get the url listed in the Location header IF the original request was a GET (i.e not a post). It will respond to 303 responses by trying to GET the redirected url whatever the original request method. When set to false, no attempt is made to get the redirected url and the result will return "error" followed by the status code and message (e.g. error 302 found)

(This is different from previous behavior whereby libUrl always attempted to GET 301 and 302 redirects whatever the original request method, but didn't handle other responses.)

libUrlSetSSLVerification <true|false> (new in 1.1.1)

When set to true (the default), libUrl will use the "with verification" form of the "open secure socket" command which uses certificates set in the SSLCertificates property. When set to false, the "without verification" form is used which enables encrypted data transfer but without being certain who you're sending to or receiving from. Once set, the property is in use for all subsequent requests until it is set differently, so BE CAREFUL with this. (i.e. don't use it unless you know what you're doing)

Other notes

Authorization

If an http or ftp url requires authorization with a user name and password, these can be included in the url in the following way:

   <protocol>://<username>:<password>@<host><path>
 

       http://dave:evad123@www.xxxxxx.com/secrets/thetruth.html
       ftp://daphne:enhp456@ftp.xxxxxx.com/gossip/really.jpg
      

For anonymous ftp, no name or password is required. The library will add the "anonymous" user name and a dummy password automatically.

Note that the name and password included in this way with an http url will only work with the Basic authentication scheme, and only for server-based authentication. To handle other authentication schemes, or to handle Proxy Authentication, see libUrlSetAuthCallback.

If the user name or password contains non-alphanumeric characters (specifically the ":", "@", "/" , "." or "|" characters if these are allowed), then these should be urlEncoded before being put into the url.

    put "jim" into tName
    put "jsmith@abc.com" into tPass
    put "ftp://" & tName & ":" & urlEncode(tPass) & "@ftp.xxx.com/title.txt" into tUrl
    get url tUrl
    

Using libUrl

To use any of the above commands and functions, the libUrl script must be available. In the Revolution development environment, this is done automatically and there is no need to take any action. When building a standalone, however, you must transfer the library. In the Distribution Builder dialog, be sure that Internet Libraries is highlited under the Resources tab. There is no need to do anything more as all transferred libraries will be available when your application starts.

In the Metacard development environment, the libUrl script is automatically loaded when you use any of the engine calls that use libUrl (get, load, delete, etc.). However, it is not automatically loaded when using any of the commands and functions that start with "libUrl" unless one of the engine calls was made previously. In this case, you must "start using" libUrl before using a libUrl command or function. In all cases, before building a Metacard standalone, you should transfer the libUrl stack as a substack of your application's main stack. You can do this using the Resource Mover underneath the Tools menu. To start using libUrl, in your main stack you should insert the following line somewhere in your scripts so that it is called before any calls that make use of libUrl are made.

     start using "libUrl"

April 11, 2006