diff --git a/CHANGES.md b/CHANGES.md index 4fa263d..bd34f0f 100644 --- a/CHANGES.md +++ b/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. diff --git a/cs/OpenProtocol/Data Classes/Message Types/MoldData.cs b/cs/OpenProtocol/Data Classes/Message Types/MoldData.cs index f36b10f..c455561 100644 --- a/cs/OpenProtocol/Data Classes/Message Types/MoldData.cs +++ b/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; } /// This constructor is internal and only used for deserialization. [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> GetFields () diff --git a/cs/doc/api_reference.md b/cs/doc/api_reference.md index ee14b52..85cb812 100644 --- a/cs/doc/api_reference.md +++ b/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#) diff --git a/cs/doc/messages_reference.md b/cs/doc/messages_reference.md index 4d1f3c8..273595c 100644 --- a/cs/doc/messages_reference.md +++ b/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 diff --git a/cs/doc/quick_reference.md b/cs/doc/quick_reference.md index 9b8f6b6..e8b214d 100644 --- a/cs/doc/quick_reference.md +++ b/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 diff --git a/doc/actions.md b/doc/actions.md index e3fda9a..9091d8a 100644 --- a/doc/actions.md +++ b/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. diff --git a/doc/alarms.md b/doc/alarms.md index c638541..61ff318 100644 --- a/doc/alarms.md +++ b/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. diff --git a/doc/cycledata.md b/doc/cycledata.md index 68c6267..20f46a5 100644 --- a/doc/cycledata.md +++ b/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. diff --git a/doc/enums.md b/doc/enums.md index 4b6fc78..a887202 100644 --- a/doc/enums.md +++ b/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