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 = {
   &nsp;{ field = 'Authorization', value = "auth_header" },
   &nsp;{ field = 'Content-Length', value = 1000 },
   &nsp;{ field = 'Content-MD5', value = LrMD5.digest( 'something' ) },
}

import "LrTasks".startAsyncTask( function()
   &nsp;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.
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 )
Sends or retrieves data using HTTP or HTTPS POST.
LrHttp.postMultipart( url, content, headers, timeout )
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.
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 )
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) The data to send.
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.
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.

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 )
Sends or retrieves MIME-Multipart data using HTTP or HTTPS POST.

First supported in version 1.3 of the Lightroom SDK.

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): The data for the chunk. Required if no file is specified.
  • 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.
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.

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