roUrlTransfer

this object is used for reading from and writing to remote servers through urls it reports transfer status using the rourlevent object brightsign enables the http //, https //, ftp\ //, and file // protocols the javascript equivalent is http object creation this object is created with no parameters createobject("rourltransfer") you must create a separate rourltransfer instance for each asset you wish to read/write ifuserdata setuserdata(user data as object) sets the user data that will be returned when events are raised getuserdata() as object returns the user data that has previously been set via setuserdata() it will return invalid if no data has been set ifidentity getidentity() as integer returns a unique number that can be used to identify when events originate from this object the ifidentity interface has been deprecated we recommend using the ifuserdata interface instead ifmessageport setport(port as romessageport) as void sets the message port to which events will be posted for asynchronous requests ifurltransfer seturl(url as string) as boolean sets the url for the transfer request this function returns false on failure use getfailurereason to learn the reason for the failure addheader(name as string, value as string) as boolean adds the specified http header this is only valid for http urls this function returns false on failure use getfailurereason() to learn the reason for the failure gettostring() as string connects to the remote service as specified in the url and returns the response body as a string this function cannot return until the exchange is complete, and it may block for a long time having a single string return means that much of the information (headers, response codes) has been discarded if you need this information, you can use asyncgettostring() instead the size of the returned string is limited to 65,536 characters gettofile(filename as string) as integer connects to the remote service as specified in the url and writes the response body to the specified file this function does not return until the exchange is complete and may block for a long time the response code from the server is returned it is not possible to access any of the response headers if you need this information, use asyncgettofile() instead asyncgettostring() as boolean begins a get request to a string asynchronously events will be sent to the message port associated with the object if false is returned, then the request could not be issued and no events will be delivered asyncgettofile(filename as string) as boolean begins a get request to a file asynchronously events will be sent to the message port associated with the object if false is returned, then the request could not be issued and no events will be delivered enableresume(enable as boolean) as boolean specifies the file creation behavior of the gettofile() and asyncgettofile() methods if this method is set to false (the default setting), each download will generate a temporary file if the download is successful, the temporary file will be renamed to the specified filename; if the download fails, the temporary file will be deleted if this method is set to true, the file with the specified filename will be created regardless of whether the download is successful or not—this allows the download to be resumed by a subsequent gettofile() or asyncgettofile() call head() as object synchronously perform an http head request and return the resulting response code and headers through an rourlevent object in the event of catastrophic failure (e g an asynchronous operation is already active), a null object is returned asynchead() as boolean begins an ansynchronous http head request events will be sent to the message port associated with the object if the request could not be issued, the method will return false and will not deliver any events postfromstring(request as string) as integer uses the http post method to post the supplied string to the current url and return the response code any response body is discarded postfromfile(filename as string) as integer uses the http post method to post the contents of the specified file to the current url and then return the response code any response body is discarded asyncpostfromstring(request as string) as boolean uses the http post method to post the supplied string to the current url events of type rourlevent will be sent to the message port associated with the object a false return indicates that the request could not be issued and no events will be delivered asyncpostfromfile(filename as string) as boolean uses the http post method to post the contents of the specified file to the current url events of the type rourlevent will be sent to the message port associated with the object a false return indicates that the request could not be issued and no events will be delivered setuserandpassword(user as string, password as string) as boolean enables http authentication using the specified user name and password note that http basic authentication is deliberately disabled due to it being inherently insecure http digest authentication is supported setmaximumreceivebytespersecond(bytes per second as double) as boolean limits the rate at which downloads are performed by the rourltransfer instance the source data rate isn't under the direct control of the brightsign player, but download rates should average below the specified value over time this method returns true on success and false on failure in event of failure, the getfailurereason() method may provide more information setmaximumsendbytespersecond(bytes per second as double) as boolean limits the rate at which uploads are performed by the rourltransfer instance this method returns true on success and false on failure in event of failure, the getfailurereason() method may provide more information setminimumtransferrate(bytes per second as integer, period in seconds as integer) as boolean causes the transfer to be terminated if the rate drops below bytes per second when averaged over period in seconds note that if the transfer is over the internet, you may not want to set period in seconds to a small number in case network problems cause temporary drops in performance for large file transfers and a small bytes per second limit, averaging fifteen minutes or more might be appropriate getfailurereason() as string may provide additional information if any of the rourltransfer methods indicate failure setheaders(a as object) as boolean asyncgettoobject(type as string) as boolean begins an asynchronous get request and uses the contents to create an object of the specified type events will be sent to the message port associated with the object if this method returns false, the request could not be issued and no events will be delievered only supported types are rosyncspec and roxmlelement asynccancel() as boolean cancels any outstanding async requests on the rourlevent object retainbodyonerror(retain as boolean) as boolean specifies whether to return the response body when there is an http error response code if retain is true, rourltransfer provides the body and headers of the response even if the http status code indicates that an error occurred (e g a 4x or 5xx status code) if retain is false, rourltransfer does not provide the body and headers of the response if the http status code indicates that an error occurred this method returns true on success, and false if it fails the default behavior of rourltransfer is equivalent to passing false into the method if retainbodyonerror() returns as false , call getfailurereason() to get details enableunsafeauthentication(enable as boolean) as boolean supports basic http authentication if true http authentication uses an insecure protocol, which might allow others to easily determine the password the rourltransfer object will still prefer the stronger digest http if it is supported by the server if this method is false (which is the default setting), it will refuse to provide passwords via basic http authentication, and any requests requiring this authentication will fail enableunsafeproxyauthentication(enable as boolean) as boolean supports basic http authentication against proxies if true (which, unlike enableunsafeauthentication() , is the default setting) http authentication uses an insecure protocol, which might allow others to easily determine the password if this method is false, it will refuse to provide passwords via basic http authentication, and any requests requiring this authentication type will fail enablepeerverification(verification as boolean) as boolean enables checking of tls/ssl certificates this method is set to true by default disabling peer verficiation allows you to bypass an expired certificate check enablehostverification(verification as boolean) as boolean enables checking of the tls/ssl certificate for the correct hostname this method is set to true by default disabling host verification allows you to accept a certificate being sent for the wrong hostname peer verification and host verification are important security checks that prevent "man in the middle" attacks these features should only be disabled after careful consideration of the security implications setcertificatesfile(filename as string) as boolean configures an alternative set of ca certificates for the connection this method is useful if the connection certificates are signed by a ca that is not on the the default trusted list (for example, if your organization uses a private ca hierarchy that is not signed by a well known root ca) this method replaces the default list, so the passed certificate file must contain all acceptable ca certificates required for the connection setclientcertificate(parameters as roassociativearray) as boolean specifies an https client certificate for use with server authentication pkcs#12 certificates are not supported this method accepts an associative array with the following parameters certificate file the filename of the client certificate file key file the filename of the key file you do not need to specify a key file if the key is embedded in the client certificate file (which might be the case when using pem format) type either "pem" or "der" passphrase the string passphrase to use if the key is encrypted obfuscated passphrase the obfuscated string passphrase to use if the key is encrypted if any of the parameters are set incorrectly, you'll likely get a 35 error when making a request setcookie(cookie as string) as boolean adds the specified cookie to the player storage and enables the cookie parsing/sending engine the cookie can be either a single line in netscape/mozilla format or a standard http style header (i e set cookie ) you can also carry out commands by passing these exact strings to the method "all" erases all cookies held in memory "sess" erases all session cookies held in memory "reload" loads all cookies from files specified by setcookiefile() calls setcookiefile(filename as string) as boolean adds cookies to the player storage using the specified cookie file and enables the cookie parsing/sending engine the cookie data can be in either netscape/mozilla format or standard http format getcookies() as rolist returns a string list of all cookies (including expired cookies) enableencodings(enable as boolean) as boolean enables http compression, which communicates to the server that the system can accept any encoding that the rourltransfer object is capable of decoding by itself this currently includes "deflate" and "gzip", which allow for transparent compression of responses clients of the rourltransfer instance see only the decoded data and are unaware of the encoding being used http compression is enabled by default in firmware versions 6 0 x and later setuserandpassword(a as string, b as string) as boolean head() as object performs a synchronous http head request and returns the resulting response code and headers through an rourlevent object in the event of catastrophic failure (e g an asynchronous operation is already active), a null object is returned escape(unescaped as string) as string converts the provided string to a url encoded string all characters that could be misinterpreted in a url context are converted to the %xx form unescape(a as string) as string geturl() as string setproxy(proxy as string) as boolean sets the name or address of the proxy server that will be used by the rourltransfer instance the proxy string should be formatted as follows "http //user\ password\@hostname\ port" it can contain up to four " " characters; each " " character can be used to replace one octet from the current ip address for example, if the ip address is currently 192 168 1 2, and the proxy is set to "proxy ", then the player will attempt to use a proxy named "proxy 192 168" setproxybypass(hostnames as array) as boolean exempts the specified hosts from the proxy setting the passed array should consist of one or more hostnames the player will attempt to reach the specified hosts directly rather than using the proxy that has been specified with the setproxy() method for example, the hostname "http //example com " would exempt "http //example com ", "http //example com 80 ", and "example domain " from the proxy setting putfromstring(a as string) as integer uses the http put method to write the supplied string to the current url and return the response code any response body is discarded; use rourltransfer syncmethod() to retrieve the response body settimeout(milliseconds as integer) as boolean terminates the transfer if the request takes longer than the specified number milliseconds note that this includes the time taken by any name lookups, so setting this value too low will cause undesirable results passing 0 to the method disables the timeout this method returns true upon success and false upon failure in the event of failure, using the getfailurereason() method may provide more information if the operation times out, the status return is 28 setuseragent(a as string) as boolean putfromfile(a as string) as integer uses the http put method to write the contents of the specified file to the current url and return the response code any response body is discarded; use rourltransfer syncmethod() to retrieve the response body asyncputfromstring(a as string) as boolean uses the http put method to write the supplied string to the current url events of type rourlevent will be sent to the message port associated with the object a false return indicates that the request could not be issued and no events will be delivered any response body is discarded; use rourltransfer asyncmethod to retrieve the response body asyncputfromfile(a as string) as boolean uses the http put method to write the contents of the specified file to the current url events of type rourlevent will be sent to the message port associated with the object a false return indicates that the request could not be issued and no events will be delivered any response body is discarded; use rourltransfer asyncmethod() to retrieve the response body delete() as object uses the http delete method to delete the resource at the current url and return the response code any response body is discarded; use rourltransfer syncmethod to retrieve the response body asyncdelete() as boolean uses the http delete method to delete the resource at the current url events of type rourlevent will be sent to the message port associated with the object a false return indicates that the request could not be issued and no events will be delivered any response body is discarded; use rourltransfer asyncmethod() to retrieve the response body clearheaders() as void removes all headers that would be supplied with an http request addheaders(a as object) as boolean adds one or more headers to http requests pass headers to this object as an roassociativearray of name/value pairs this method returns true upon success and false upon failure all headers that are added with this method will continue to be sent with http requests until clearheaders() is called syncmethod(a as object) as object begins a synchronous http request using the specified parameters (see the parameters described for asyncmethod ) if the parameters are malformed then the method returns invalid and calling getfailurereason() may provide more information, otherwise the method returns a rourlevent instance containing the results of the request it may take several minutes for a failing request to time out and brightscript will be blocked waiting during that time, so use of this method is not recommended the asyncmethod method does not block and should be used instead setrelativelinkprefix(prefix as string) as boolean places the specified prefix in front of the url if the url is relative use this method to easily make file /// urls drive agnostic bindtointerface(interface as integer) as boolean ensures that the request only goes out over the specified network interface by default, the request goes out over the most appropriate network interface (which may depend on the routing metric configured via ronetworkconfiguration) note that if both interfaces are on the same layer 2 network, this method may not always work as expected due to the linux weak host model the default behavior can be selected by passing 1 to the method this method returns false upon failure in this case, the getfailurereason() method may provide more information asyncmethod(parameters as roassociativearray) as boolean begins an asynchronous http method request using the specified parameters (see below) if the request is started successfully, the method returns true and and will deliver an event if the request could not be started, then the method returns false and will not deliver an event if this occurs, you may be able to use the getfailurereason() method to get more information the parameters are specified using an roassociativearray instance that may contain the following members name type description method string an http method normal values include "head", "get", "post", "put", and "delete" other values are supported; however, depending on server behavior, they may not work as expected request body string string a string containing the request body request body file string the name of a file that contains the request body response body string boolean if specified and set to true, the response will be stored in a string and provided via the rourlevent getstring() method response body file string the name of the file that will contain the response body the body is written to a temporary file and then renamed to the specified filename if successful response body resume file string the name of the file that will contain the response body for a get request, a range header is sent based on the current size of the file, which is written in place rather than using a temporary file response body object string uses the response body to create an object of the specified type see the entry for asyncgettoobject() for supported object types response pipe roarray use a pipeline of handlers to process the response body as it is received see below for more details the roarray response for response pipe consists of one or more roassociativearray instances containing a filter description (see below) the last associative array is usually an output filter name type description hash string calculate a hash (digest) of the data using the specified algorithm as it passes through the pipeline supported hashes include the following "crc32", "md5", "sha1", "sha256", "sha384", "sha512" the resulting hash can be retrieved as a hexadecimal string using the rourlevent gethash() method decompress string decompress the response body using the specified algorithm currently, the only supported algorithm is “gzip” it is often easier to use an http content encoding rather than explicitly decompressing the body prefix capture integer capture the specified number of bytes (between 1 and 16384) from the start of the stream and store them separately the bytes can be retrieved using the rourlevent getprefix() method, but they cannot be passed on to subsequent filters output file string output the pipeline to the specified file the output is written to a temporary file and then renamed to the specified filename if successful output string boolean if specified and set to true, the response will be stored in a string and provided via the rourlevent getstring() method the following example code specifies an array of handlers to filter the response body of an http request url = createobject("rourltransfer") pipe = \[ { decompress "gzip"}, { hash "md5" }, { output file "test txt" } ] result = url asyncmethod({ method "get", response pipe pipe })