HttpFunctions

HTTP functions

wbc.setHTTPHeaders

• Description: Sets additional http headers to be used in the next HTTP request.
• Threading: foreground/immediate
• Function: wbc.setHTTPHeaders(headerObj)
• Arguments
  • headerObj: An object whose properties and their values become key/value pairs representing HTTP headers. To clear existing HTTP headers, pass an empty object ({})
• Returns
  • OK/ERROR
• Notes: None

wbc.ajaxRequest

• Description: Performs a 'GET' HTTP Ajax request.
• Threading: Background with callback.
• Function: wbc.ajaxRequest(url, callback)
• Arguments:
  • url: The url and querystring parameters of the ajax request.
  • callback: A bound js callback that receives an evt object. The evt object has the following properties:
    • func: internal function name ('uisdk_Download')
  • threadId: the thread Id matching that returned by the original call to wbc.ajaxRequest()
  • url: identical to the url passed in during the function call.
  • status: the status string. Callback does not occur until this is set to 'DONE'
  • httpStatusCode: the HTTP response status code
  • httpStatusText: the HTTP response status text
  • httpHeaders: array of HTTP response header strings (each member of an array - the line from the HTTP response header)
  • body: the body section of the HTTP response (usually HTML, JSON, OR XML)
  • bodyBase64: the body section of the HTTP response encoded as a base64 string.
  • complete: Should always be 100 for this call.
  • totalSend: the total amount of data (in bytes) sent to the server.
  • sent: the amount of data that is sent to the server so far (in bytes). Should always match totalSend in this function.
  • totalReceive: the total amount of data (in bytes) received from the server.
  • received: the amount of data that received from the server so far (in bytes). Should always match totalReceive in this function.
• Returns:
  • ERROR/INVALID
  • threadID: Id of the thread used to send the request.
• Notes:
  • During this request, the public property wbc.ajaxBusy is set to true. This becomes false when the request completes, whether successful or error.
  • Additional HTTP request headers can be set using wbc.setHTTPHeaders()

wbc.downloadFile

• Description: Downloads a file via HTTP to a local file system folder.
• Threading: Background with callback
• Function: wbc.downloadFile(onlineSource, localDest, callback, context)
• Arguments:
  • onlineSource: Source URL of the file to be downloaded.
  • localDest: Target location (full path and filespec) specifying where to download the file.
  • context: Optional. Any object or value that may help the callback function logic.
  • callback: bound JS function exposing the following properties:
  • string func: internal function name ('uisdk_DownloadFile')
  • int threadId: the thread Id (the same as returned by the original function call)
  • string url: the remote URL (the same as passed to the original function call)
  • string status: the status string. Can be one of the following:
  • 'BUSY': the operation is in progress
  • 'ERROR': the operation was terminated or some error occurred
  • 'DONE': the operation is successfully complete.
  • string file: the local destination filespec (the same as passed to the original function call)
  • int httpStatusCode: the HTTP response status code
  • string httpStatusText: the HTTP response status text
  • array httpHeaders: array of HTTP response header strings, one for each header
  • string body: the body section of the HTTP response (usually HTML) - the body field is filled only upon receiving the 'DONE' status.
  • float complete: the percentage showing the progress of the download process (from 0 till 100%). Because the total amount to download is not always can be determined at the beginning, the complete field may not always show the actual percentage. But it is set to 100% when the download is successfully completed.
  • int totalSend: the total amount of data (in bytes) that is to be sent to the server.
  • int sent: the amount of data that is sent to the server so far (in bytes).
  • int totalReceive: the total amount of data (in bytes) that is to be received from the server.
  • int received: the amount of data that is received from the server so far (in bytes).
  • object context: the context object if passed into the function.
• Returns:
  • INVALID/ERROR
  • threadID: Id of the background thread performing the download.
• Notes:
  • The localDest parent folder must already exist, or an ERROR will result in the callback.
  • If the file already exists it will be overwritten.
  • If additional request headers are required, these can be specified beforehand by calling wbc.setHTTPHeaders()

wbc.uploadFile

• Description: Uploads a file to an HTTP server via POST method.
• Threading: background with progress callback.
• Function: wbc.uploadFile(localSource, uploadUrl, callback)
• Arguments:
  • localSource: The full path and filename of the file to be uploaded.
  • uploadUrl: The URL of the active server script capable of processing HTTP POST file uploads.
  • callback: a bound JS function that will receive an evt object with the following properties:
    • string func: internal function name ('uisdk_UploadFile')
  • int threadId: the thread Id
  • string url: the remote URL specified in the initial call
  • string file: the local file name specified in the initial call.
  • string status: the status string. Can be one of the following:
    • 'BUSY': in progress
    • 'ERROR': the operation was terminated or some error occurred
    • 'DONE': the operation completed successfully.
  • string response: the response string that is returned by the server in response to the posted data. Empty until the status is 'DONE'.
  • float complete: the percentage showing the progress of the upload process (0 - 100)
  • int totalSend: the total amount of data (in bytes) that is to be sent to the server.
  • int sent: the amount of data that is sent to the server so far (in bytes).
  • int totalReceive: the total amount of data (in bytes) that is to be received from the server.
  • int received: the amount of data that is received from the server so far (in bytes).
• Returns:
  • ERROR/INVALID
  • Thread Id of upload thread.
• Notes:
  • Uploading a file via HTTP post requires that file have a POST parameter name. This name is hardcoded to 'file' in wbc.js
  • A sample upload PHP script is available on request.
  • WARNING: this wrapper function is relatively new and has not (yet) been well tested. If problems arise, use the raw function uisdk_UploadFile() instead.

wbc.setHTTPTimeout

• Description: Sets the timeout value for any HTTP operations.
• Threading: foreground/immedaite
• Function: wbc.setHTTPTimeout(milliSec)
• Arguments:
  • milliSec: number of millseconds to wait for a response before declaring the request timed out.
• Returns:
  • OK/INVALID
• Notes:
  • Has no effect on HTTP operations already in progress.
  • If no call to this function is made, HTTP operations timeout after 3000 milliseconds.