WebConnections
New to Analytica 6.5
A «webConnection» is a special data object returned by ReadFromUrl when you open an asynchronous communication channel. There are three types of asynchronous connections: a fully asynchronous (RESTful) connection, a streaming Server-Sent Events (SSE) connection, and a websocket connection.
Once you have a «webConnection» object, you interact with it using the methods described on this page. These start with underscores since they are somewhat esoteric and aren't of use in a broader scope -- they are only used as methods of a «webConnection».
Function _WebConnectionStatus( wc )
The «wc» parameter is a «webConnection» object return by ReadFromUrl.
Returns the current status of a web connection. In general, there are multiple return values:
- The connection stage. One of
'Connecting'
,'Waiting'
,'ResponseReady'
,'Done'
and'Closed'
. - HTTP code
- HTTP status text
- Response headers
- Content-type
When using an asynchronous communication channel, you will want to test the status to make sure it hasn't closed, or (if you want to work on something else) that a response is ready to be read. When a response is ready, _WebConnectionRead
will return it immediately.
Function _WebConnectionClose( wc )
Closes the connection with the server.
You can also close the connection simply be releasing the «webConnection» object. If you release it, calling _WebConnectionClose is entirely optional.
Even if you don't close it explicitly, the server on the other side of the connection may close the connection, or it may close due to a network outage.
Function _WebConnectionRead( wc, block )
Reads the next incoming message. Waits (blocks) for the next message to arrive by default. Returns immediately if you specify the optional «block» parameter and set it to false. It also returns immediately if the connection status is 'Done'
or 'Closed'
. When it returns immediately without a pending message to return, the result is Null.
For a fully asynchronous connection type (where you specified connectionType:'asynchronous'
in the ReadFromUrl call), the there will be only one (non-Null) message, which will contain the entire message.
For an SSE or websocket connection, you will typically call this many times, reading one incoming message with each call.
Function _WebConnectionSend( wc, message )
Sends a message on a websocket connection. Does nothing for non-websocket «webConnection» objects.
Enable comment auto-refresher