Accept null/empty values in Field parameter of ReadMoldDataMessage.

CHANGES.md

@@ -1,10 +1,23 @@
+Release 4.2.1
+=============
+
+Enhancements
+------------
+
+- Setting `Field` to null or an empty/white-space string in
+  `ReadMoldDataMessage` now returns a `MoldDataMessage` with the
+  full set of buffered mold setting values instead of causing an
+  exception.  Under this situation, a `MoldDataValueMessage` will
+  not be returned.
+
+
 Release 4.2
 ===========
 
 Enhancements
 ------------
 
-- Messages can optinally contain a unique `ID` field (randomly
+- Messages can optionally contain a unique `ID` field (randomly
   generated) for tracking purposes. A new method `CreateUniqueID`
   creates this unique ID, over-writing whatever is in the `ID`
   field previously.

cs/OpenProtocol/Data Classes/Message Types/MoldData.cs

@@ -43,21 +43,18 @@ public class ReadMoldDataMessage : Message
 		public uint ControllerId { get; }
 		public string Field { get; }
 
-		public ReadMoldDataMessage (uint ControllerId, string field, int Priority = 0) : base(Priority)
+		public ReadMoldDataMessage (uint ControllerId, string field = null, int Priority = 0) : base(Priority)
 		{
-
 			this.ControllerId = (ControllerId > 0) ? ControllerId : throw new ArgumentOutOfRangeException(nameof(ControllerId));
-			this.Field = !string.IsNullOrWhiteSpace(field) ? field : throw new ArgumentNullException(nameof(field));
+			this.Field = !string.IsNullOrWhiteSpace(field) ? field : null;
 		}
 
 		/// <remarks>This constructor is internal and only used for deserialization.</remarks>
 		[JsonConstructor]
 		internal ReadMoldDataMessage (string ID, long Sequence, uint ControllerId, string field, int Priority) : base(ID, Sequence, Priority)
 		{
-			if (string.IsNullOrWhiteSpace(field)) throw new ArgumentNullException(nameof(field));
-
 			this.ControllerId = (ControllerId > 0) ? ControllerId : throw new ArgumentOutOfRangeException(nameof(ControllerId));
-			this.Field = !string.IsNullOrWhiteSpace(field) ? field : throw new ArgumentNullException(nameof(field));
+			this.Field = !string.IsNullOrWhiteSpace(field) ? field : null;
 		}
 
 		public override IEnumerable<KeyValuePair<string, object>> GetFields ()

cs/doc/api_reference.md

@@ -1,7 +1,8 @@
-iChen® 4.1 Open Protocol™ .NET Library API Reference
-==================================================================
+iChen® 4 Open Protocol™ .NET Library API Reference
+==================================================
 
 Copyright © Chen Hsong Holdings Ltd.  All rights reserved.  
+`iChen.OpenProtocol.dll` version: 4.1 and up  
 Document Version: 4.1  
 Last Edited: 2018-01-23
 
@@ -19,7 +20,7 @@ The .NET Framework required for this assembly is .NET Standard 1.6 or above.
 WebSocket Communications
 ------------------------
 
-All communications with the iChen® 4.1 Server is performed through an
+All communications with the iChen® Server is performed through an
 industry-standard WebSocket interface (IETF RFC 6455).
 
 The default port (configurable) of the WebSocket interface is 5788.
@@ -28,7 +29,7 @@ Secured WebSocket connections with TLS/SSL encryption (via protocol `wss://`)
 are also supported.
 
 Use your favorite WebSocket client library to connect to the server via
-WebSocket. For example (assuming the iChen® 4.1 server resides at the
+WebSocket. For example (assuming the iChen® server resides at the
 URL `ichen.example.com`), a C# client may connect to the server like the
 following:
 
@@ -64,10 +65,10 @@ starting from version 4.5 and for Windows 8 and up only. For Windows 7 or
 below, use a third-party WebSocket client library such as `SuperWebSocket`.
 
 
-How the iChen® 4.1 Server Processes Messages
--------------------------------------------
+How the iChen® Server Processes Messages
+----------------------------------------
 
-The iChen® 4.1 server is a *massively parallel* execution engine, which
+The iChen® server is a *massively parallel* execution engine, which
 means that messages are not guaranteed to be processed *in order*. In
 addition, messages of higher priority are always processed before messages of
 lower priority, as much as possible.
@@ -97,7 +98,7 @@ information in the JSON message.
 
 #### Return Value
 
-A `Message`-based class representing the iChen® 4.1 message.
+A `Message`-based class representing the iChen® message.
 
 #### Example (C#)
 
@@ -132,7 +133,7 @@ message class object. The type parameter `T` should be the message type class.
 
 #### Return Value
 
-A `Message`-based class of type `T` representing the iChen® 4.1 message.
+A `Message`-based class of type `T` representing the iChen® message.
 
 #### Example (C#)
 

cs/doc/messages_reference.md

@@ -1,11 +1,11 @@
-iChen® 4.1 Open Protocol™ .NET Library Messages Reference
+iChen® 4 Open Protocol™ .NET Library Messages Reference
 =======================================================
 
 Copyright © Chen Hsong Holdings Ltd.  All rights reserved.  
 .NET Framework Required: .NET Standard 1.6  
-For `iChen.OpenProtocol.dll` version: 4.1.2 and up  
-Document Version: 4.1.2  
-Last Edited: 2018-10-22
+`iChen.OpenProtocol.dll` version: 4.2.1 and up  
+Document Version: 4.2.1  
+Last Edited: 2019-03-29
 
 
 Introduction
@@ -778,9 +778,11 @@ This class implements the `RESP_MOLD` message, which is sent from the
 iChen® 4.1 Server to the client in response to a [`RequestMoldDataMessage`](#requestmolddatamessage)
 message.
 
+#### Important
+
 Mold settings can be numerous (i.e. more than 1,000), but not all
 variables/fields are used. In order to reduce payload size, variables/fields
-with zero values are not included in the resultant data dictionary.
+with **zero values** are **NOT** included in the resultant data dictionary.
 
 ### Properties
 
@@ -849,10 +851,12 @@ ReadMoldDataMessage
 The iChen® 4.1 Server keeps a cache of the states of all mold settings
 for each controller. This class implements the READ_MOLD_DATA message which is
 sent to the iChen® 4.1 Server to read the current value of a particular
-mold setting.
+mold setting based on the cached values.
 
 The server responds with a [`MoldDataValueMessage`](#molddatavaluemessage)
-message.
+message (if `Field` is set) including the current value of the requested mold
+setting, or a [`MoldDataMessage`](#molddatamessage) including the current
+values of all mold settings (if `Field` is `null`, empty or white-space).
 
 ### Properties
 
@@ -861,7 +865,7 @@ message.
 |`Sequence`          |`Int64`  |`sequence`    |`number` |*Inherited from [`Message`](#message)*     |
 |`Priority`          |`Int32`  |`priority`    |`number` |*Inherited from [`Message`](#message)*     |
 |`ControllerId`      |`UInt32` |`controllerId`|`number` |Unique ID of the controller    |
-|`Field`             |`String` |`field`       |`string` |Name of the mold setting to read.|
+|`Field`             |`String` |`field`       |`string` |Name of the mold setting to read, `null` for all.|
 
 ### JSON Format Example
 

cs/doc/quick_reference.md

@@ -1,8 +1,9 @@
-iChen® 4.1 Open Protocol™ .NET Library Quick Reference
-====================================================================
+iChen® 4 Open Protocol™ .NET Library Quick Reference
+====================================================
 
 Copyright © Chen Hsong Holdings Ltd.  All rights reserved.  
 .NET Framework Required: .NET Standard 1.6  
+`iChen.OpenProtocol.dll` version: 4.1 and up  
 Document Version: 4.1  
 Last Edited: 2018-10-22
 

doc/actions.md

@@ -1,4 +1,4 @@
-iChen®; 4.1 Open Protocol™ Library Reference - Action Codes
+iChen®; 4 Open Protocol™ Library Reference - Action Codes
 =========================================================
 
 Copyright © 2016 Chen Hsong Holdings Ltd.  All rights reserved.

doc/alarms.md

@@ -1,4 +1,4 @@
-iChen® 4.1 Open Protocol™ Library Reference - Alarm Codes
+iChen® 4 Open Protocol™ Library Reference - Alarm Codes
 =======================================================
 
 Copyright © 2016 Chen Hsong Holdings Ltd.  All rights reserved.

doc/cycledata.md

@@ -1,4 +1,4 @@
-iChen® 4.1 Open Protocol™ Library Reference - Cycle Data
+iChen® 4 Open Protocol™ Library Reference - Cycle Data
 ======================================================
 
 Copyright © 2016 Chen Hsong Holdings Ltd.  All rights reserved.

doc/enums.md

@@ -1,4 +1,4 @@
-iChen® 4.1 Open Protocol™ Library Reference - Enum Types
+iChen® 4 Open Protocol™ Library Reference - Enum Types
 ======================================================
 
 Copyright © 2016 Chen Hsong Holdings Ltd.  All rights reserved.
@@ -8,7 +8,7 @@ Languages
 ---------
 
 `Languages` represent the language for textual information sent between the
-iChen® 4.1 server and clients.
+iChen® server and clients.
 
 |Code|Numeric Value|Description|
 |----|:-----------:|-----------|
@@ -27,7 +27,7 @@ iChen® 4.1 server and clients.
 Filters
 -------
 
-`Filters` controls what type(s) of messages the iChen® 4.1 server will send to each client.
+`Filters` controls what type(s) of messages the iChen® server will send to each client.
 
 ### Regular messages