DecSoft App Builder

Websocket description

The Websocket is a non visual (don't appear in the screen at runtime) control that allows to establish a bidirectional connection between the app and the app server. This means that we can send to the server certain message, but we can also receive messages from the server.

There is a Websocket sample app included with the installation of DecSoft App Builder. Take a look to see this control in action!

Websocket at designtime

The Websocket control put at your disposition the below designtime properties or variables. Designtime means here that these properties are only available in designtime and not in runtime.

Websocket at runtime

The Websocket control put at your disposition the below runtime properties or variables. You can set almost all these variables in designtime, and, they are also available to be use when the app is running. Note that we named here these variables in a capitalized way, because is like you can see it in the designtime control's inspector, however, at runtime we use the lower camel case way.

Websocket methods

The Websocket control put at your disposition the below methods. You can use these methods in runtime in order to perform various control related tasks.

Websocket events

The Websocket control put at your disposition the below events handlers:

Websocket designtime properties

Websocket Top property

Designtime. Integer variable. The Top property stores the top position of the control in pixels. This value is only take in consideration at designtime, since this is a non visual control, which do not appear in the screen at runtime.

Websocket Left property

Designtime. Integer variable. The Left property stores the left position of the control in pixels. This value is only take in consideration at designtime, since this is a non visual control, which do not appear in the screen at runtime.

Websocket Width property

Designtime. Integer variable. The Width property stores the width of the control in pixels. This value is only take in consideration at designtime, since this is a non visual control, which do not appear in the screen at runtime.

Websocket Height property

Designtime. Integer variable. The Height property stores the height of the control in pixels. This value is only take in consideration at designtime, since this is a non visual control, which do not appear in the screen at runtime.

Websocket Locked property

Designtime. Boolean variable. The Locked property determines if the control can be moved or resized in app view designer or not. This value is only take in consideration at designtime, since this is a non visual control, which do not appear in the screen at runtime.

Websocket runtime properties

Websocket Name property

Runtime. String variable. The Name control property stores the name of the Websocket control as you set in designtime. The Name property value must be unique for the same app view, dialog or frame, that is, it's possible to have more than one "http1" in the app, if that controls resides in different app views, dialogs or frames. Note that you must consider this variable as read only: change the name of a control in runtime can cause unexpected results.

Websocket Url property

Runtime. String variable. The Url control property stores the URL of the Websocket server to connect with. Set this variable before call to the control open() method.

Websocket Protocols property

Runtime. String variable. The Protocols control property stores a comma separated string with the optional protocols, which specifies protocols that the Websocket server must support for the connection to be successful. You can leave this variable empty when no needed.

Websocket Status property

Runtime. Number variable. The Status control property has a "0" (zero) value indicating that the connection has not yet been established. A value of "1" indicates that the connection is established and communication is possible (then you can use the control open() method). A value of "2" indicates that the connection is going through the closing handshake. And finally a value of "3" indicates that the connection has been closed or could not be opened.

Websocket Code property

Runtime. Number variable. The Code control property is available in the control Close event and can have one of the below values:

Status code Name Description
0999 Reserved and not used.
1000 CLOSE_NORMAL Normal closure; the connection successfully completed whatever purpose for which it was created.
1001 CLOSE_GOING_AWAY The endpoint is going away, either because of a server failure or because the browser is navigating away from the page that opened the connection.
1002 CLOSE_PROTOCOL_ERROR The endpoint is terminating the connection due to a protocol error.
1003 CLOSE_UNSUPPORTED The connection is being terminated because the endpoint received data of a type it cannot accept (for example, a text-only endpoint received binary data).
1004 Reserved. A meaning might be defined in the future.
1005 CLOSE_NO_STATUS Reserved.  Indicates that no status code was provided even though one was expected.
1006 CLOSE_ABNORMAL Reserved. Used to indicate that a connection was closed abnormally (that is, with no close frame being sent) when a status code is expected.
1007 The endpoint is terminating the connection because a message was received that contained inconsistent data (e.g., non-UTF-8 data within a text message).
1008 The endpoint is terminating the connection because it received a message that violates its policy. This is a generic status code, used when codes 1003 and 1009 are not suitable.
1009 CLOSE_TOO_LARGE The endpoint is terminating the connection because a data frame was received that is too large.
1010 The client is terminating the connection because it expected the server to negotiate one or more extension, but the server didn't.
1011 The server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.
10121014 Reserved for future use by the WebSocket standard.
1015 Reserved. Indicates that the connection was closed due to a failure to perform a TLS handshake (e.g., the server certificate can't be verified).
10161999 Reserved for future use by the WebSocket standard.
20002999 Reserved for use by WebSocket extensions.
30003999 Available for use by libraries and frameworks. May not be used by applications.
40004999 Available for use by applications.

Websocket Reason property

Runtime. Number variable. The Reason control property is available in the control Close event and stores the reason for the Websocket connection close.

Websocket Message property

Runtime. Mixed variable. The Message control property is available in the control Message event and stores the message that has been sent to the app from the websocket server.

Websocket runtime methods

Websocket open() method

Runtime method. You can use this Websocket control method to open the connection with the Websocket server. The open() method is expected to be fired after call to this control method. This method don't require any arguments.

Websocket send() method

Runtime method. You can use this Websocket control method to send a message to the websocket server. This method require the below argument:

Name Type Description
message String The message to be send to the websocket server.

Websocket close() method

Runtime method. You can use this Websocket control method to gracefully close the connection with the websocket server. This method don't require any arguments.

Websocket events

Websocket Open event

The Open event hander is fired after call to the open() method and the websocket connection has been established.

Websocket Message event

The Message event hander is fired when the app receive a message from the websocket server. The message is stored in the control Message property.

Websocket Close event

The Close event hander is fired when the connection with the websocket server has been closed. Look at the Status, Code and Reason properties for more information about the connection close reason.

Websocket Error event

The Error event hander is fired when an error occurs. Look at the Status, Code and Reason properties for more information about the error.

Websocket events variables

The below JavaScript variables are available in all the referred Websocket control events handlers:

Name Type Description
event Mixed This variable is received in almost all control events. You can use this variable to stop the propagation of the event, to access the HTML element who fire the event and more.
self Object Stores the control object. This is a shortcut to the control variable, and it's available since we are talking about specific control events.
view Object

Stores the current app view or dialog. This variable allow us to access to that view or dialog properties and methods and also their controls properties and methods. For example, you can access to a control properties using the variable "view.yourControlName", suposing the control is named "yourControlName".

views Object Stores all the loaded app views. Note that loaded views mean that the app views has been previously show to the user. It's possible to access to the app view controls properties like "views.view1.yourControlName", suposing the view is named "view1" and the control is named "yourControlName". In the same way we can access to other controls of the view and to other loaded views and their controls.
frames Object Stores all the app frames. You can use this variable to access to all the app frames and their controls.
dialogs Object Stores all the app dialogs. You can use this variable to access to all the app dialogs and their controls.
app Object Stores all the app properties and methods. You can use this variable to access to all the app properties and app methods.