bool webopen(web WebVar, string URL);

 

The WOPEN statement opens a website using port 80 HTTP and associates it with the specified variable of type WEB. There are a number of important considerations when implementing network functions in a plugin.

When the WOPEN statement is called, a connection is made to the specified URL immediately. It is standard practice for webservers to terminate connections that do not request any data for a specified period of time. Therefore after opening a website with WOPEN you should begin reading data from the website as soon as possible. This will prevent the connection from timing out. This is not a flaw in the implementation of WOPEN, it is a standard practice of TCP/IP and webservers.

As with any network/Internet access, the WOPEN statement is dependant upon network conditions. If traffic to the specified website is extremely slow it may take up to 60 seconds to either connect to the site or time out. During this time your plugin code will stall. You should bear this in mind when developing plugin code. A stalled plugin cannot affect Brass itself or any other plugins, but is not user-friendly and may cause the user to force Brass to terminate it. If you are confident that network access will always be reasonably fast you may ignore this issue, however there is a technique to handle this gracefully. In a standard application it is normal to perform network operations in a thread. If you are unfamiliar with multithreaded applications, they appear to allow 2 different pieces of code to execute at the same time. If the network operations are performed in a separate thread and stall they do not affect the rest of the application. Shiny does not explicitly support creating worker threads, however Brass plugins do work in a threaded model. The Update handler is always called in a separate thread to the rest of the plugin code. This allows the plugin developer to emulate multithreaded code. By creating a global WEB variable and calling WOPEN in the Update handler you can ensure that the rest of your plugin code will continue to execute regardless of whether the WOPEN call stalls due to network issues. Because the Update handler is constantly and repeatedly called throughout the life of the plugin it is sensible to use 2 boolean variables to control the WOPEN statement. Boolean 1 should be used to signal whether to call WOPEN (if boolean == true then call wopen), boolean 2 should be used to signal when the WOPEN statement has completed (if wopen(...) == true then boolean2 = true).

The WOPEN statement creates a "raw" HTTP connection to the specified URL. This means that all data read from the connection is returned in raw HTTP/HTML form. This consideration is discussed further in wreadline and wreadbytes.

If you need to post data to an HTML form (or simulate an HTTP POST), refer to wpost.

Secure SSL/TLS connections (HTTPS) are supported through the optional third parameter. A "referrer" is supported through the optional fourth parameter. By default HTTPS is not used, and no referrer is supplied.

Parameters

WebVar

A variable declared as type WEB, which will be associated with the opened website and used for all access to it.

URL

The full HTTP URL to the resource to access. As of Shiny v0.2 there is no requirement to include the "http://" protocol specifier prefix.

Secure

Optional. When True, Brass attempts to establish an HTTPS connection to the specified webserver. This parameter is False by default.

Referrer

Optional. A URL specifying the "fake" referrer for the URL resource in parameter 2. Many webservers will deny access to resources unless the access request has come from another resource on that same server. For example, when you browse to a webpage all the images on that page will appear, as the referrer for the resource will be the webserver itself. However if you try to directly view one of the images your access may be denied as the referrer will be incorrect. This is a standard mechanism for webservers to deny image hotlinking. By specifying a referrer in this parameter you can usually bypass such restrictions.

 

Return Value

TRUE if opening the site suceeded, otherwise FALSE. The return value of WOPEN can be used for further operations.

Example Code

web BrassSite;
bool Result = wopen(BrassSite, "http://www.amazingbrass.co.uk");

// Alternative testing:
if(wopen(BrassSite, "http://www.amazingbrass.co.uk") == FALSE)
    // handle error

// Open an HTTPS connection with a referrer
web SecureSite;
Result = wopen(SecureSite, "http://fictional.site", True, "http://othersite.com");