tsNet Command Reference | Tech Strategies

Command: tsNetCABundle

Sets a CA bundle to be used for SSL connections within the tsNet external.

tsNetCABundle <pCAFile>

Operating Systems supported: Mac OS X, Windows, Linux, iOS and Android

Platforms supported: Desktop, Server and Mobile

Example:

tsNetCABundle “/etc/ssl/ca-bundle.crt”

Parameters:

pCAFile: The path to the file to be used as the CA bundle.

Command: tsNetClose

Closes all open connections and disables the tsNet external.

tsNetClose

Operating Systems supported: Mac OS X, Windows, Linux, iOS and Android

Platforms supported: Desktop, Server and Mobile

Example:

tsNetClose

Command: tsNetCloseConn

Removes the specified connection from memory.

tsNetCloseConn <pConnectionID>

Operating Systems supported: Mac OS X, Windows, Linux, iOS and Android

Platforms supported: Desktop, Server and Mobile

Example:

tsNetCloseConn “myConnID”

Parameters:

pConnectionID: The identifier of the transfer to remove.

The result:

The tsNetCloseConn command sets the result to empty if the connection was found. If the connection identifier is invalid an error will be returned that starts with “tsneterr:”.

Command: tsNetCreateMissingDirs

Enable or disable automatic creation of missing directories when uploading files via FTP or SFTP.

tsNetCreateMissingDirs <pEnable>

Operating Systems supported: Mac OS X, Windows, Linux, iOS and Android

Platforms supported: Desktop, Server and Mobile

Example:

tsNetCreateMissingDirs true

Parameters:

pEnable: Set to either true or false. The default value is false.

Function: tsNetCustom

Send an asynchronous custom request to a server.

tsNetCustom(<pConnectionID>, <pURL>, <pRequest>, <pHeaders>, <pCallback>, [<pSettings>])

Operating Systems supported: Mac OS X, Windows, Linux, iOS and Android

Platforms supported: Desktop, Server and Mobile

Example 1:

   local tHeaders, tResult
   put tsNetCustom(“1”, “http://www.livecode.com/file.dat”, “DELETE”, \
      tHeaders, “transferComplete”) into tResult

Example 2:

   local tHeaders, tResult
   put tsNetCustom(“1”, “ftp://user:pass@ftp.example.com/”, “NLST”, \
      tHeaders, “transferComplete”) into tResult

Example 3:

   on transferComplete pID, pResult, pBytes, pCurlCode
      local tData, tHeaders
      if pCurlCode is not 0 then
         answer tsNetRetrError(pID)
      end if
      put tsNetRetrData(pID, tError) into tData
      tsNetCloseConn pID
      answer “Server returned:” & tData
   end transferComplete

Parameters:

pConnectionID: A arbitrary user-defined label for the connection that is used when retrieving any details of the transfer.
pURL: The URL formatted as ‘scheme://host:port/path’ and URL-encoded as outlined in [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt). The following schemes are supported: ‘tftp’, ‘ftp’, ‘ftps’, ‘http’, ‘https’ and ‘sftp’. For SFTP connections (Business Edition only), the path is not relative to the user’s home directory, but must be the full system path.
pRequest: For HTTP transfers, specify the custom HTTP method to be sent in the request. This is useful particularly for sending HTTP DELETE requests. For FTP/SFTP transfers, this is the raw command (e.g. NLST) that should be used to send a specialised directory listing command. SFTP commands are only supported in the Business Edition of LiveCode.
pHeaders: For HTTP(s) connections, the headers to be sent to the server. For all other protocols, leave this blank.
pCallback: Specify a callback message to be sent to the current object when the transfer is complete.
pSettings: An array of additional settings that control how the transfer is initiated.

Returns:

The tsNetCustom function returns empty on success. On error, the return value will be a string containing the error starting with “tsneterr:”.

Description:

This function sends a callback message on completion. Use tsNetRetrData to access the returned data. To save memory, it is recommended to call tsNetCloseConn when the connection is no longer needed.

The callback message will be sent with four parameters: the connection identifier, the status code sent back by the server, the number of bytes transferred and the cURL result code.

The cURL result code parameter in the callback message will be 0 for successful transfers. For any errors, further information can be
retrieved by calling the tsNetRetrError function.

The settings array can consist of the following elements (not all of the settings make sense for every possible transfer type):

"byte_range": (Introduced in tsNet version 1.4.0) Specify the range of data to be downloaded. This can be in the format of “X-Y”, “X-“, “-Y” or “X-Y,N-M” where X, Y, N and M and byte indexes. Some HTTP servers may ignore this request.

"cookie_file": (Introduced in tsNet version 1.4.0) Specify a filename to load cookies from. If this setting is present, the internal cookie engine will be enabled and the cookies stored in the file loaded into the engine.

"cookies": (Introduced in tsNet version 1.4.0) The contents of this setting will be used to set a cookie in a HTTP request. It should be in the format of COOKIE_NAME=COOKIE_CONTENTS. Specify multiple cookies by separating them with a semi-colon. This setting does not enable the internal cookie engine of tsNet.

"cookie_jar": (Introduced in tsNet version 1.4.0) Specify a filename to write all known cookies to. If this setting is present, the internal cookie engine of tsNet will be enabled. Note that this file will only be written to at unspecified times. Use the “cookie_list” setting below to force the file to be updated.

"cookie_list": (Introduced in tsNet version 1.4.0) Set this to a list of cookies (one per line) in Netscape / Mozilla format or regular HTTP (Set-Cookie:) style format to add to the internal cookie engine. There are also several strings that when passed to this setting will perform additional actions. Passing in the string “ALL” will erase all cookies held in memory. “SESS” will erase all session cookies in memory. “FLUSH” will write all cookies stored in memory to the file specified by the “cookie_jar” setting. “RELOAD” will reload all cookies from file specified by “cookie_file”.

"disable_eprt": (Introduced in tsNet version 1.4.0) Set this option to true to stop tsNet from using the EPRT command when performing active FTP transfers.

"disable_epsv": (Introduced in tsNet version 1.4.0) Set this option to true to stop tsNet from using the EPSV command when performing passive FTP transfers.

"dont_modify_path": (Introduced in tsNet version 1.4.0) Set this option to true to stop tsNet from squashing “/../” and “/./” components from the URL path. RFC 3986 specifies that these should be removed.

“enable_tcp_keepalive”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to send TCP keepalive probes.

“expect100_timeout”: (Introduced in tsNet version 1.4.0) Specify the number of milliseconds to wait for a response with a HTTP 100 (Continue) or HTTP 417 (Expectation Failed) status after setting a HTTP request containing an Expect: 100-continue header. The default is 1000ms.

"fail_on_http_error": Set to true to specify that HTTP status codes greater than 400 should be considered an error.

"force_basic_auth": (Introduced in tsNet version 1.3.1) Set to true to force HTTP basic authentication rather than allow tsNet to detect what authentication methods are supported by the server.

"force_digest_auth": (Introduced in tsNet version 1.3.5) Set to true to force HTTP digest authentication rather than allow tsNet to detect what authentication methods are supported by the server.

“ftp_filemethod”: (Introduced in tsNet version 1.4.0) Set this to “nocwd” or “singlecwd” to change the method used by FTP to reach a particular file. Using “nocwd” will ensure all FTP commands use the full path to the file on the server. Using “singlecwd” will make tsNet issue a single CWD command to change to the directory that the file resides in before performing any other action on the file. The default is to issue a CWD command for each path part in the URL prior to performing any other action on the file in accordance with RFC 1738.

“ftp_ssl_ccc”: (Introduced in tsNet version 1.4.0) Set this to “passive” or “active” to disable the SSL/TLS encryption after authenticating with the FTP server. All further communication on the command channel with the FTP server will be unencrypted. Use “passive” to only disable the encryption after the server requests it. Setting this to “active” will initiate the encryption shutdown.

“ftp_user_alt”: (Introduced in tsNet version 1.4.0) Specify an alternate string to use for authentication if the standard FTP username and password negotiation fails.

“if_mod_since”: (Introduced in tsNet version 1.4.0) If the last modified time (in seconds since 1 Jan 1970) of the file is later than this, then download the file.

“if_unmod_since”: (Introduced in tsNet version 1.4.0) If the last modified time (in seconds since 1 Jan 1970) of the file is earlier than this, then download the file.

“ignore_content_length”: (Introduced in tsNet version 1.4.0) Set this option to true to ignore the content length specified in HTTP or FTP transfers. tsNet will complete the download when the server ends the connection.

“interface”: (Introduced in tsNet version 1.4.0) Specify the interface, IP address or host name to be used for the outgoing connection.

“junk_session_cookies”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to ignore all cookies loaded via the “cookie_file” setting that are session cookies.

“keepalive_idle”: (Introduced in tsNet version 1.4.0) When “enable_tcp_keepalive” is set to true, use this setting to specify the number of second to wait while the connection is idle before sending keepalive probes. The default is 60 seconds.

“keepalive_interval”: (Introduced in tsNet version 1.4.0) When “enable_tcp_keepalive” is set to true, use this setting to specify the number of seconds to wait between sending keepalive probes. The default is 60 seconds.

“local_port_range”: (Introduced in tsNet version 1.4.0) Set the number of consecutive ports above the port specified by the “local_port_start” setting to try when finding an available port for a connection.

“local_port_start”: (Introduced in tsNet version 1.4.0) Set the local port number of the socket to be used for the connection. It is recommended to also set “local_port_range” if you use this setting.

“max_file_size”: (Introduced in tsNet version 1.4.0) Specify the maximum size of a file to download. If the file exceeds this value, the transfer will not start. This option has no affect is the file size is not known prior to the download.

“max_recv_speed”: (Introduced in tsNet version 1.4.0) This option specifies the number of bytes per second to limit a download transfer to. Setting this to 0 disables any limiting.

“max_send_speed”: (Introduced in tsNet version 1.4.0) This option specifies the number of bytes per second to limit an upload transfer to. Setting this to 0 disables any limiting.

"no_reuse": Set to true to specify that the connection to the server should be disconnected and not left open for any future connections.

"no_transfer": Set to true to connect to the server but not perform any transfer.

"password": Set to a string containing the password to be used in any authentication requests from the server.

"post_commands": (Business Edition only) Set to a list of raw FTP/SFTP commands (one per line) that should be executed on the server directly after any transfer.

“post_on_301”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to not convert POST requests to GET requests after a 301 response.

“post_on_302”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to not convert POST requests to GET requests after a 302 response.

“post_on_303”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to not convert POST requests to GET requests after a 303 response.

"pre_commands": (Business Edition only) Set to a list of raw FTP/SFTP commands (one per line) that should be executed on the server prior to any transfer.

“proxy_auth_basic”: (Introduced in tsNet version 1.4.0) Set this option to true to force tsNet to use basic authentication when authenticating with a proxy server.

“proxy_auth_digest”: (Introduced in tsNet version 1.4.0) Set this option to true to force tsNet to use digest authentication when authenticating with a proxy server.

"proxy_headers": Set to a list of headers (one per line) that should be sent to any proxy server that is being used.

“proxy_http_10”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to use HTTP/1.0 for any CONNECT tunnelling.

“referer”: (Introduced in tsNet version 1.4.0) The contents of this setting will be used as the HTTP Referer: header sent as part of a HTTP request.

“resolve_hosts”: (Introduced in tsNet version 1.4.0) Specify a list (one per line) of host to IP addresses to use when resolving host name for a request. Each line must be in the format of “HOSTNAME:PORT:ADDRESS”.

“resume_from”: (Introduced in tsNet version 1.4.0) Specify the number of bytes at which you want a transfer to start downloading or uploading.

"save_sent_headers": Set to true to specify that external should store a copy of all the headers that it sends to the server. This must be set to true to use the tsNetRetrSentHeaders function.

“skip_pasv_ip”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to ignore the IP address from the server’s 227 response message. tsNet will connect the data connection via the same IP address it used to set up the control connection.

“ssl_ciphers”: (Introduced in tsNet version 1.4.0) Use this setting to specify a list of SSL ciphers (separated by colons) to be used when negotiating SSL connections.

“ssl_client_cert”: (Introduced in tsNet version 1.4.1) Specify the filename of a client SSL certificate to use for authentication to the server.

“ssl_client_cert_type”: (Introduced in tsNet version 1.4.1) Set to the format of the client SSL certificate. Supported formats are “PEM”, “DER” and “P12”.

“ssl_client_key”: (Introduced in tsNet version 1.4.1) Specify the filename of a SSL private key file that matches the client SSL certificate.

“ssl_client_key_pass”: (Introduced in tsNet version 1.4.1) Set to the password for the SSL private key.

“ssl_client_key_type”: (Introduced in tsNet version 1.4.1) Set to the format of the SSL private key. Supported formats are “PEM” and “DER”.

“ssl_proxy_client_cert”: (Introduced in tsNet version 1.4.1) Specify the filename of a proxy client SSL certificate to use for authentication to the HTTP proxy.

“ssl_proxy_client_cert_type”: (Introduced in tsNet version 1.4.1) Set to the format of the proxy client SSL certificate. Supported formats are “PEM”, “DER” and “P12”.

“ssl_proxy_client_key”: (Introduced in tsNet version 1.4.1) Specify the filename of a SSL private key file that matches the proxy client SSL certificate.

“ssl_proxy_client_key_pass”: (Introduced in tsNet version 1.4.1) Set to the password for the SSL private key.

“ssl_proxy_client_key_type”: (Introduced in tsNet version 1.4.1) Set to the format of the SSL private key. Supported formats are “PEM” and “DER”.

"ssh_host_public_key": Set to the 128 bit MD5 checksum of the remote host's public key. The connection will be rejected unless they match.

"ssh_passphrase": (Business Edition only) Set to the passphrase for any included private key.

"ssh_private_key": (Business Edition only) Set to the private key file (including full system path) to be used in SFTP transfers.

“trace”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to include all inbound and outbound data when using tsNetSetDebugCallback() rather than just header and informational data. When this option is set, a third parameter will be posted to the debug callback function specifying the type of data that is being passed to the callback function.

“transfer_encoding”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to request the response be sent in a compressed Transfer-Encoding (if the server supports it) that will be automatically uncompressed by tsNet when it is received.

“trust_location_auth”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to continue to send authentication details when following any HTTP redirects.

“try_ssl”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to try to connect via SSL. If the connection fails to establish via SSL, connect without using SSL.

“tunnel_http_proxy”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to tunnel all operations (all protocols) through the HTTP proxy.

“use_ascii_transfer”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to use ASCII mode for FTP transfers.

“use_pret”: (Introduced in tsNet version 1.4.0) Set this option to true to tell tsNet to send a PRET command before sending PASV/EPSV when performing passive FTP transfers.

"use_ssl": Set to true to connect using Transport Layer Security (TLS) for SMTPS and FTPS (explicit) connections.

"username": Set to a string containing the username to be used in any authentication requests from the server.

“use_ssl_control”: (Introduced in tsNet version 1.4.0) Set this option to true to ensure all control communication is encrypted.

“user_agent”: (Introduced in tsNet version 1.4.0) The contents of this setting will be used as the HTTP User-Agent: header sent as part of a HTTP request.

Function: tsNetCustomSync

Send a synchronous custom request to a server.

tsNetCustomSync(<pURL>, <pRequest>, <xHeaders>, <rOutHeaders>, <rResult>, <rBytes>, [<pSettings>])

Operating Systems supported: Mac OS X, Windows, Linux, iOS and Android

Platforms supported: Desktop, Server and Mobile

Example 1:

   local tHeaders, tRecvHeaders, tResultCode, tBytes, tData
   put tsNetCustomSync(“http://www.livecode.com/file.dat”, “DELETE”, \
      tHeaders, tRecvHeaders, tResultCode, tBytes) into tData

Example 2:

   local tHeaders, tRecvHeaders, tResultCode, tBytes, tData
   put tsNetCustomSync(“ftp://user:pass@ftp.example.com/”, “NLST”, \
      tHeaders, tRecvHeaders, tResultCode, tBytes) into tData

Parameters:

pURL: The URL formatted as ‘scheme://host:port/path’ and URL-encoded as outlined in [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt). The following schemes are supported: ‘tftp’, ‘ftp’, ‘ftps’, ‘http’, ‘https’ and ‘sftp’. For SFTP connections, the path is not relative to the user’s home directory, but must be the full system path.
pRequest: For HTTP transfers, specify the custom HTTP method to be sent in the request. This is useful particularly for sending HTTP DELETE requests. For FTP/SFTP transfers, this is the raw command (e.g. NLST) that should be used to send a specialised directory listing command.
xHeaders: For HTTP(s) connections, the headers to be sent to the server. For all other protocols, leave this blank. The contents of this variable will be replaced when the function returns with the headers that were sent to the server if the “save_sent_headers” array setting is specified below.
rOutHeaders: This variable will contain the headers that were returned from the server on completion.
rResult: This variable will contain the status code sent by the server to the last command that was issued during the transfer. For SFTP connections, this will always be 0. On error, the return value will be a string containing the error starting with “tsneterr:”.
rBytes: This variable will contain the number of bytes that were downloaded during the connection.
pSettings: An array of additional settings that control how the transfer is initiated.

Returns:

The tsNetCustomSync function returns the data retrieved from the server on success.