Namespace LrHttp

This namespace allows you to send and receive data using HTTP. The function can only be called within an asynchronous task. This can be the implicit task that Lightroom starts for your processRenderedPhotos function, or one that you start using LrTasks.

In the event of network error, all LrHttp GET and POST methods will return nil, plus an info object. The info object is the headers (if any data were received before the error occurred). It will also contain an entry for "error" which is a table containing the following keys: The key "errorCode" which is a string value (one of the errorCodes, listed below), "name" which is a localized description of the error, and "nativeCode" which is the error code provided by the operating system. Finally, the info object may also contain a key "partial_data" for any data returned by the http connection before the error occurred.

These are the possible "errorCode" values: "cancelled", "badURL", "timedOut", "cannotFindHost", "cannotConnectToHost", "resourceUnavailable", "networkConnectionLost", "redirectError", "badServerResponse", "authenticationError", "authenticationError", "securityError", "serverCertificateHasBadDate", "serverCertificateHasUnknownRoot".

The following example, using LrHttp.post, demonstrates the format of the headers parameter to many of these functions:

 local LrHttp = import "LrHttp"
 local LrMD5 = import "LrMD5"
 
 local headers = {
     { field = 'Authorization', value = "auth_header" },
     { field = 'Content-Length', value = 1000 },
     { field = 'Content-MD5', value = LrMD5.digest( 'something' ) },
 }
 
 import "LrTasks".startAsyncTask( function()
     local result, hdrs = LrHttp.post( "http://www.example.com", "somestring", headers )
 end )

Summary

LrHttp.get( url, headers, timeout )
Retrieves data over the network using HTTP or HTTPS GET.
LrHttp.openUrlInBrowser( url )
Opens a URL in the user's preferred web browser.
LrHttp.parseCookie( cookie, decodeUrlEncoding )
Converts a received "Set-Cookie" field into a Lua table.
LrHttp.post( url, postBody, headers, method, timeout, totalSize )
Sends or retrieves data using HTTP or HTTPS POST.
LrHttp.postMultipart( url, content, headers, timeout, callbackFn, suppressFormData )
Sends or retrieves MIME-Multipart data using HTTP or HTTPS POST.

Functions

LrHttp.get( url, headers, timeout )
Retrieves data over the network using HTTP or HTTPS GET.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. url
(string) The URL to get.
2. headers
(table, optional) A table of tables, one for each header. Each header table has a 'field' and a 'value' entry. Unless you specify a 'Content-Type' header, Lightroom will add such a header with a value of 'text/plain'. To force the omission of a 'Content-Type' header, specify a 'Content-Type' header with a value of 'skip'.
3. timeout
(number) The length of time (in seconds) to wait during each phase of the connection before canceling the request. This parameter will be ignored by Lightroom 1.3 and 1.4.

Return values

  1. (string) The body of the HTTP response.
  2. (table) A table of tables, one for each header. Each header table has a 'field' and a 'value' entry. The headers table contains the key "status" whose value is the HTTP status (an integer). Cookies are stored in a 'Set-Cookie' header; there can be multiple 'Set-Cookie' headers

See also

LrHttp.parseCookie
LrHttp.openUrlInBrowser( url )
Opens a URL in the user's preferred web browser.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. url
(string) The URL to open.
LrHttp.parseCookie( cookie, decodeUrlEncoding )
Converts a received "Set-Cookie" field into a Lua table. Each field is a separate table key, with the field's value as the table value. For fields that do not have an explicit value (such as. 'secure') the value is set to true.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. cookie
(string) The received cookie value from a 'Set-Cookie' HTTP header.
2. decodeUrlEncoding
(Boolean, optional) True to decode URL-encoded content. Default is true.
LrHttp.post( url, postBody, headers, method, timeout, totalSize )
Sends or retrieves data using HTTP or HTTPS POST. This function is limited to a single chunk of post data. It must be called from within LrFunctionContext.postAsyncTaskWithContext().

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. url
(string) The URL to post to.
2. postBody
(string (or, as of Lightroom 4.1, a function)) The data to send. As of Lightroom 4.1, this may also be a callback function to be called to provide data chunks. This function must return nil when all the data has been provided, which will be the last time it is called.
3. headers
(table, optional) A table of tables, one for each header. Each header table has a 'field' and a 'value' entry. To specify the content type of your post, include a "Content-Type" header. Unless you specify a 'Content-Type' header, Lightroom will add such a header with a value of 'text/plain'. To force the omission of a 'Content-Type' header, specify a 'Content-Type' header with a value of 'skip'.
4. method
(string, optional) The name of the HTTP method to use. Default is "POST".
5. timeout
(number) The length of time (in seconds) to wait during each phase of the connection before canceling the request. This parameter will be ignored by Lightroom 1.3 and 1.4.
6. totalSize
(number) The total size of the post body, when a byte getter function is passed in for the 'postBody' parameter, which is only supported starting with Lightroom 4.1.

Return values

  1. (string) The body of the HTTP response.
  2. (table) A table of tables, one for each header. Each header table has a 'field' and a 'value' entry. The headers table contains the key "status" whose value is the HTTP status (an integer). Cookies are stored in a 'Set-Cookie' header; there can be multiple 'Set-Cookie' headers if more than one cookie was set.

See also

LrFunctionContext, LrHttp.parseCookie
LrHttp.postMultipart( url, content, headers, timeout, callbackFn, suppressFormData )
Sends or retrieves MIME-Multipart data using HTTP or HTTPS POST.

First supported in version 1.3 of the Lightroom SDK.

Assumes that the content consists of 'form-data' and inserts a 'Content-Disposition' header into each MIME part. As of Lightroom 5.0, this behavior can be altered via the optional 'suppressFormData' parameter. See below.

Parameters

1. url
(string) The URL to post to.
2. content
(table) An array of content chunks. The data for each chunk is either in a file, or in a string. If both are specified, the file is used. Each entry in the table should contain:
  • name (optional, string): The name of the multipart chunk.
  • fileName (optional, string): The name of a file to pass in the MIME header.
  • filePath (optional, string): The path to the file.
  • value (optional, string (or, as of Lightroom 4.0, a function)): The data for the chunk. As of Lightroom 4.0, this may also be a callback function to be called to provide data chunks. If this approach is used, the content table may only contain one entry. This function must return nil when all the data has been provided, which will be the last time it is called. Required if no file is specified.
  • totalSize (optional, number): As of Lightroom 4.0, required if 'value' is a function. Specifies the total size of the data which will be provided by the data provider function, before it returns nil to indicate that all data has been provided.
  • contentType (optional, string): The content MIME type.
3. headers
(table, optional) A table of tables, one for each header. Each header table has a 'field' and a 'value' entry. A Content-Length header will be added automatically if one isn't specified. (It is difficult for the caller of this API to calculate the correct length ahead of time.)
4. timeout
(number) The length of time (in seconds) to wait during each phase of the connection before canceling the request. This parameter will be ignored by Lightroom 1.3 and 1.4.
5. callbackFn
(function, optional) Will be called back with a number between 0 and 1 indicating the % of the upload that has completed
6. suppressFormData
(Boolean, optional) If true, a 'Content-Disposition' header will not be added to each MIME chunk.

Return values

  1. (string) The body of the HTTP response.
  2. (table) A table of tables, one for each header. Each header table has a 'field' and a 'value' entry. The headers table contains the key "status" whose value is the HTTP status (an integer). Cookies are stored in a 'Set-Cookie' header; there can be multiple 'Set-Cookie' headers if more than one cookie was set.

See also

LrHttp.parseCookie