roAssetFetcher

this object contains functions for downloading files to the pool brightsign enables the http //, https //, ftp\ //, and file // protocols the javascript equivalent is assetfetcher docid\ hg03eush xkkpfofwdgcz object creation the roassetfetcher object must be passed an roassetpool instance upon creation createobject("roassetfetcher", pool as roassetpool) example pool = createobject("roassetpool", "pool") fetcher = createobject("roassetfetcher", pool) ifassetfetcher getfailurereason() as string returns an error string if an roassetfetcher method has failed (this is usually indicated by returning false) the error string may help diagnose the failure setuserandpassword(user as string, password as string) as boolean sets the default user and password strings to be used for all download requests that are not otherwise marked using the following attributes \<auth inherit=”no”> or \<auth user=”user” password =”password”> 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 roassetfetcher 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 enableencodings(enable as boolean) as boolean enables http compression, which communicates to the server that the system can accept any encoding that the roassetfetcher object is capable of decoding by itself (this behavior is enabled by default) supported encodings currently include "deflate" and "gzip", which allow for transparent compression of responses clients of the roassetfetcher instance see only the decoded data and are unaware of the encoding being used asyncdownload(assets as roassetcollection) as boolean begins populating the asset pool using the files listed in the passed roassetcollection instance files that are not already in the pool will be downloaded automatically events are raised during the download process to indicate whether individual file downloads have succeeded or failed; finally, a single event will be raised indicating whether the entire asset collection has been downloaded successfully or not see the roassetfetcherevent and roassetfetcherprogressevent entries for more details asyncsuggestcache(spec as roassetcollection) as boolean begins downloading the required files from the passed roassetcollection instance, then disconnects shortly afterward if the player is set to use a suitably configured proxy (either globally or via the setproxy() method), then the proxy will continue to download the files, making them readily available for asyncdownload() calls in the future this method generates an roassetfetcherevent message with response code 202 ("accepted") to indicate success other errors will be reported as usual the final all files complete event code will always be 2 ("event all failed") because the download does not complete asynccancel() as boolean cancels any pending “async” requests note that, prior to and during this method call, events associated with an asynchronous action may be queued no more events will be queued once this call returns we recommend collecting any pending events prior to calling any further “async” methods on the same object to avoid confusion enablepeerverification(verification as boolean) as boolean enables checking of tls/ssl certificates this method is set to true by default disabling peer verification 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 verficiation 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 addheader(name as string, value as string) as boolean specifies a header that will be passed to http requests made by the roassetfetcher instance a particular download will not include the header if it has the \<headers inherit=”no”> attribute in the sync spec setheaders(headers as roassociativearray) as boolean specifies all headers that will be passed to http requests made by the roassetfetcher instance this method removes any previously set headers a particular download will not include the headers if it has the \<headers inherit=”no”> attribute in the sync spec setproxy(proxy as string) as boolean sets the name or address of the proxy server that will be used by the roassetfetcher instance the proxy string should be formatted as "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 roassetfetcher instance 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 "http //www example com " from the proxy setting setfileprogressintervalseconds(interval as integer) as boolean specifies the interval (in seconds) between progress events when an individual file is being downloaded setting the interval to 1 disables all progress events setting the interval to 0 specifies that events should be generated as often as possible, though this will slow down the transfer process if the interval is set to 0 or any positive integer, events will always be generated at the start and end of the file download irrespective of elapsed time the default interval is 300 seconds setfileretrycount(count as integer) as boolean specifies the maximum number of times each file download will be retried before moving on to the next file download the default retry count is five setrelativelinkprefix(prefix as string) as boolean specifies a prefix that will be appended to the front of relative links in the sync spec normally, this method is used to make file /// uris drive agnostic, but it can also be used to reduce the size of the sync spec if all files are stored in the same place non relative links are not affected by this method bindtointerface(interface as integer) as boolean ensures that the http request goes out over the specified network interface (0 for ethernet or 1 for wifi) the default behavior (which can be specified by passing 1) is to send requests using the most appropriate network interface, which may depend on the routing metric configured via the ronetworkconfiguration object if both interfaces are on the same layer 2 network, this method may not work as expected due to the linux weak host model setmaximumreceivebytespersecond(bytes per second as double) as boolean limits the rate at which downloads are performed by the roassetfetcher 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 setminimumtransferrate(bytes per second as integer, period in seconds as integer) as boolean sets the minimum transfer rate for each file download a transfer will 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 may be appropriate ifmessageport setport(port as romessageport) posts messages of type roassetfetcherevent and roassetfetcherprogressevent to the attached message port 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