Finished documentation of Error Generation feature #8

Author: AndreaV-Lsi

README.md

@@ -21,8 +21,8 @@ Look in the example folder for a comprehensive set of code examples covering the
 
 ## Note About Terminology
 
-Please note that within this library **resource names**, as defined in
-the WebSocket protocol specification, are referred to as **services**.
+Please note that within this library **"resource names"**, as defined in
+the WebSocket protocol specification, are referred to as **"services"**.
 
 # Library
 
@@ -51,7 +51,7 @@ which the client should connect.
 This actor's role is solely that of launching and managing the stop of
 "WebSocket Server" actors listening on at a specific port and interface
 address ("Launch Server Msg" and "Stop Server Msg" messages). The actor
-will ensure that the launched "WebSocket Server" doesn’t conflict on
+will ensure that the launched "WebSocket Server" actor doesn’t conflict on
 interface and port resources. If the server is already running at that
 port or on the specified interface the method sends just the server
 enqueuer to the client. If the server is not running it will be
@@ -80,7 +80,7 @@ protocol will take care of communicating the failure to the client.
 
 ## WebSocket Service.lvclass
 
-It forwards packets received from the connected WebSocket Clients to its
+It forwards packets received from the connected "WebSocket Client" actors to its
 subscriber actor as "WebSocket Connection Handler Msg" messages. It
 allows the subscriber to send data to a specified client ("Send to Peer
 Msg" message of the parent "WebSocket Connection" class) or to all
@@ -95,11 +95,11 @@ WebSocket service actor enqueuer.
 
 ## Abstract messages
 
-Two abstract messages must be subclassed to allow the interaction of either a WebSocket Server, a WebSocket Service or a WebSocket Client with the corresponding subscriber actor.
+Two abstract messages must be subclassed to allow the interaction of either a "WebSocket Server", a "WebSocket Service" or a "WebSocket Client" actor with the corresponding subscriber actor.
 
 ### WebSocket Connection Handler Msg.lvclass
 
-This abstract message is sent by either the WebSocket Client or by the
+This abstract message is sent by either the "WebSocket Client" or by the
 WebSocket Service to the subscriber Actor on four events:
 
 -   Connect
@@ -119,12 +119,35 @@ corresponding event.
 
 ### WebSocket Server-Service Enqueuer Msg.lvclass
 
-This abstract message is used either by the WebSocket Server Manager or
-by the WebSocket Server to send the just launched/added Server/Service
+This abstract message is used either by the **WebSocket Server Manager** actor or
+by the **WebSocket Server** actor to send the just launched/added Server/Service
 Enqueuer to the subscriber actor requesting the operation. Each
 subscriber actor requesting the operation should subclass this message
-and then override the Do.vi in which the Server/Service Enqueuer is
-stored in the requesting actor.
+and then override the Do.vi wherein the Server/Service Enqueuer can be read from the suitable abstract message property and stored in the subscriber actor.
+
+## Errors
+All custom error generated by this library are forwarded to the appropriate subscriber actor to be handled by the "Handle Error" method. If such method is not overridden by the subscriber actor, the actor will stop when the subscribed actor generates an errors. All the errors generated the connection level will result 
+
+The custom errors defined by this library are the following:
+
+### 512000: The WebSocket connection dropped for unknown reasons.**
+
+This error is generated when the connection is dropped for an unknown reason most likely related to problems with the TCP/IP connection. In such cases a "Drop" type "WebSocket Connection Handler Msg" concrete message will be fired, allowing the subscriber (either a to a "WebSocket Client" actor or a "WebSocket Server" actor) to react to this situation by overriding the Drop method within the message concrete implementation.  Please note that if the Keepalive system is activated and a peer doesn't reply within the specified timeout, no error is generated. Rather, only the "Drop" type message is fired.
+
+### 512001: The WebSocket Server could not establish a connection to the peer for unknown reasons.
+
+This error is generated by the "WebSocket Server" actor when he is not able to establish a connection to the WebSocket client. In such cases the is presumed that the "WebSocket Server" actor is still able to establish new connections if requested.
+
+### 512002: The WebSocket Server listener could not be created. Server is going to stop.
+This is generated upon a "WebSocket Server" actor launch in case a TCP/IP listener cannot be created. In such case the Actor will stop.
+
+### 512003: The WebSocket Server listener became invalid for unknown reasons. The WebSocket Server is not accepting the definition of any new server.
+
+This is generated within the lifetime of a "WebSocket Server" actor when the TCP/IP listener becomes invalid. In such case the Actor will not stop, but will not be accepting the addition of any new service from the subscriber.
+
+### 512004: The WebSocket Server is not accepting the definition of any new service.
+In case one tries to add a service to a "WebSocket Server" actor that stopped to accept the addition of new services (see Error 512004) the subscriber demanding an addition will receive this error.
+
 
 # API
 
@@ -144,7 +167,7 @@ Before launch the "Server Manager Actor" can be configured with the Keepalive se
 
 ![](media/Server%20Menager%20Configuration.png)
 
-**Keepalive** The Keepalive settings will be active for all the WebSocket Servers launched by the "WebSocket Server Manager Actor"
+**Keepalive** The Keepalive settings will be active for all the WebSocket Servers launched by the "WebSocket Server Manager" actor
 
 **Certificate Chain** specifies an array of Distinguished Encoding Rules (DER) certificates. The certificates must be supplied depth-first: the server's certificate, followed by the Certificate Authority (CA) that signs the certificate of the server, on up to the root CA. For more details see LabVIEW TLS examples. 
 
@@ -198,13 +221,13 @@ Enqueuer Msg.lvclass*”.
 alt="A computer screen shot of a message Description automatically generated" />
 
 **Subscriber Enqueuer** specifies the enqueuer of the actor that has
-subscribed to the previously launched WebSocket Server actor.
+subscribed to the previously launched "WebSocket Server" actor.
 
-**Message Enqueuer in** specifies the enqueuer of the WebSocket Server
-Manager actor to be stopped.
+**Message Enqueuer in** specifies the enqueuer of the "WebSocket Server
+Manager" actor to be stopped.
 
 **Listener Settings** specifies the listener settings for the previously
-launched WebSocket Server actor.
+launched "WebSocket Server" actor.
 
 **Handshake timeout** specifies the timeout of the handshake when the
 client establishes a WebSocket connection to the server.
@@ -215,7 +238,7 @@ Enqueuer Msg.lvclass*”.
 
 ## WebSocket Server
 
-In case the WebSocket Server Actor is manually launched the following
+In case the "WebSocket Server" actor is manually launched the following
 properties are available to configure it (the port must be entered)
 before its launch
 
@@ -248,12 +271,12 @@ alt="A computer screen shot of a message Description automatically generated" />
 created) child of the abstract message “*WebSocket Server-Service
 Enqueuer Msg.lvclass”.*
 
-**Message Enqueuer in** specifies the enqueuer of the WebSocket Server
+**Message Enqueuer in** specifies the enqueuer of the "WebSocket Server"
 actor.
 
 **Service Name** specifies the name of the service.
 
-**Subscriber Enqueuer** specifies the enqueuer of the actor that subscribes to the WebSocket Server Actor.
+**Subscriber Enqueuer** specifies the enqueuer of the actor that subscribes to the "WebSocket Server" actor.
 
 **WebSocket Data Handler** specifies the concrete message (to be
 created) child of the abstract message “*WebSocket Connection Handler
@@ -285,7 +308,7 @@ we want to send the data
 
 ## WebSocket Client 
 
-The following properties of the WebSocket Client actor must be set
+The following properties of the "WebSocket Client" actor must be set
 before launching it:
 
 ![](media/image9.png)
@@ -307,7 +330,7 @@ created) child of the abstract message “*WebSocket Connection Handler
 Msg.lvclass”.*
 
 **Subscriber Enqueuer** specifies the enqueuer of the actor (must be
-created) that subscribes to the WebSocket Client Actor.
+created) that subscribes to the "WebSocket Client" actor.
 
 **Keepalive** specifies the Keepalive settings for the Client (see
 definition above).

WebSocket-Actor.vipb

@@ -1,7 +1,7 @@
-<VI_Package_Builder_Settings Version="2020.1" Created_Date="2023-10-14 14:13:00" Modified_Date="2024-11-11 13:43:39" Creator="AndreaVaccaro(LSInst" Comments="" ID="96f1c4342f2a2ad4dc1b779bdc0d6cd8">
+<VI_Package_Builder_Settings Version="2020.1" Created_Date="2023-10-14 14:13:00" Modified_Date="2024-11-12 01:01:01" Creator="AndreaVaccaro(LSInst" Comments="" ID="0b783b623b854da272694ebf5a245556">
   <Library_General_Settings>
     <Package_File_Name>LS_Instruments_AG_lib_WebSocket_Actor</Package_File_Name>
-    <Library_Version>1.1.0.9</Library_Version>
+    <Library_Version>1.1.0.10</Library_Version>
     <Auto_Increment_Version>false</Auto_Increment_Version>
     <Library_Source_Folder>.</Library_Source_Folder>
     <Library_Output_Folder>vipm packages</Library_Output_Folder>
@@ -409,7 +409,7 @@ Look at the LabVIEW example folder for a comprehensive set of examples.
         <Path>WebSocket Actor\WebSocket Server\typedefs\Listener Settings.ctl</Path>
         <VI_Title/>
       </Items_Data>
-      <GUID>DC2C81D4ED07D5FED4778C7E989521D9</GUID>
+      <GUID>016F89B944D3405E43D3DE75F66F8DF6</GUID>
     </Functions_Palette_Data>
     <Functions_Palette_Data>
       <Parent_Palette_Index>0</Parent_Palette_Index>
@@ -458,7 +458,7 @@ Look at the LabVIEW example folder for a comprehensive set of examples.
         <Path>WebSocket Actor\WebSocket Actor Palette\WebSocket Server-Service Enqueuer Msg.vi</Path>
         <VI_Title/>
       </Items_Data>
-      <GUID>AC6F7C38337730B4B47266109F7BE110</GUID>
+      <GUID>BE70D2E87DEB3E95654A0A55EA102A8A</GUID>
     </Functions_Palette_Data>
     <Functions_Palette_Data>
       <Parent_Palette_Index>0</Parent_Palette_Index>
@@ -535,7 +535,7 @@ Look at the LabVIEW example folder for a comprehensive set of examples.
         <Path>WebSocket Actor\WebSocket Actor Palette\WebSocket Service.vi</Path>
         <VI_Title/>
       </Items_Data>
-      <GUID>16F1928E68EE6DBAD1033183FA2B55F1</GUID>
+      <GUID>96E02BA8DD9C7A270EAA5081715D00C2</GUID>
     </Functions_Palette_Data>
   </Library_Palette_Definition>
 </VI_Package_Builder_Settings>

WebSocket-Actors-errors.txt

@@ -10,16 +10,16 @@ Custom error codes defined by the "WebSocket-Actors" library.
 </nifamily>
 </nicomment>
 <nierror code="512000">
-The WebSocket connection dropped for unknown reasons
+The WebSocket connection dropped for unknown reasons.
 </nierror>
 <nierror code="512001">
-The WebSocket Server could not estabilish a connection to the peer for unknown reasons
+The WebSocket Server could not establish a connection to the peer for unknown reasons.
 </nierror>
 <nierror code="512002">
-The WebSocket Server listener could not be created. Server is going to stop
+The WebSocket Server listener could not be created. Server is going to stop.
 </nierror>
 <nierror code="512003">
-The WebSocket Server listener became invalid for unknown reasons. The WebSocket Server is not accepting the definition of any new server
+The WebSocket Server listener became invalid for unknown reasons. The WebSocket Server is not accepting the definition of any new server.
 </nierror>
 <nierror code="512004">
 The WebSocket Server is not accepting the definition of any new service.