Z003pktn/library update firmware v3 1 0 (#36)

 Remove Unnecessary Usings
 Implement Cancellationtoken in ServiceFactory
 Implement Cancellationtoken in ApiHttpClientRequestHandler
 Implement Cancellationtoken in ApiBackupHandler
 Implement Cancellationtoken in DirectoryHandler, FileHandler
 Implement Cancellationtoken in WebAppDeployer, ResourceHandler
Extend ApiHttpClientRequestHandler for new Methods with Firmware V3.1.0

 Api.GetQuantityStructures
 Api.ChangePassword
 Api.GetPasswordPolicy
 Api.GetAuthenticationMode
 WebServer.SetDefaultPage
 WebServer.ReadDefaultPage
 PlcProgram.DownloadProfilingData
 PlcProgram.Browse with CodeBlocks support
 Plc.ReadModeSelectorState
 Plc.SetSystemTime
 Plc.SetTimeSettings
 Alarms.Browse
 Alarms.Acknowledge
 Syslog.Browse
 DiagnosticBuffer.Browse
 Modules.DownloadServiceData
 Project.ReadLanguages

README.md

@@ -243,6 +243,7 @@ Plc Version | Client Library Version
 2.9.x              | 1.0.x
 2.9.x              | 2.0.x
 3.0.x              | 2.1.x
+3.0.x              | 2.2.x
 
 ## SIMATIC S7-1200:
 Plc Version | Client Library Version

src/Webserver.API/Enums/ApiAlarmAcknowledgementState.cs

@@ -0,0 +1,21 @@
+// Copyright (c) 2023, Siemens AG
+//
+// SPDX-License-Identifier: MIT
+
+namespace Siemens.Simatic.S7.Webserver.API.Enums
+{
+    /// <summary>
+    /// The acknowledgement state of the alarm
+    /// </summary>
+    public enum ApiAlarmAcknowledgementState
+    {
+        /// <summary>
+        /// Alarm is not acknowledged
+        /// </summary>
+        Not_Acknowledged = 0,
+        /// <summary>
+        /// Alarm is acknowledged
+        /// </summary>
+        Acknowledged = 1
+    }
+}

src/Webserver.API/Enums/ApiAlarmsBrowseFilterAttribute.cs

@@ -0,0 +1,53 @@
+// Copyright (c) 2023, Siemens AG
+//
+// SPDX-License-Identifier: MIT
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
+using System.Runtime.Serialization;
+
+namespace Siemens.Simatic.S7.Webserver.API.Enums
+{
+    /// <summary>
+    /// Possible filters for ApiAlarmsBrowse request
+    /// </summary>
+    [JsonConverter(typeof(StringEnumConverter))]
+    public enum ApiAlarmsBrowseFilterAttribute
+    {
+        /// <summary>
+        /// Filter for the alarm text.
+        /// </summary>
+        [EnumMember(Value = "alarm_text")]
+        AlarmText = 1,
+        /// <summary>
+        /// Filter for the info text.
+        /// </summary>
+        [EnumMember(Value = "info_text")]
+        InfoText = 2,
+        /// <summary>
+        /// Filter for the alarm status. The value will contain either "incoming" or "outgoing".
+        /// </summary>
+        [EnumMember(Value = "status")]
+        Status = 3,
+        /// <summary>
+        /// Filter for the UTC timestamp on when the alarm went into incoming or outgoing state, provided as ISO 8601 string. <br/>
+        /// This attribute does not consider the timestamp of acknowledgement. The precision will be in nanoseconds.
+        /// </summary>
+        [EnumMember(Value = "timestamp")]
+        Timestamp = 4,
+        /// <summary>
+        /// Filter for the acknowledgement. The acknowledgement exist if the alarm is acknowledgeable. If the alarm was not configured as acknowledgeable alarm, then no acknowledgement will be returned regardless of this filter.
+        /// </summary>
+        [EnumMember(Value = "acknowledgement")]
+        Acknowledgement = 5,
+        /// <summary>
+        /// Filter for the the alarm number.
+        /// </summary>
+        [EnumMember(Value = "alarm_number")]
+        AlarmNumber = 6,
+        /// <summary>
+        /// Filter for the producer of the alarm.
+        /// </summary>
+        [EnumMember(Value = "producer")]
+        Producer = 7
+    }
+}

src/Webserver.API/Enums/ApiAuthenticationMode.cs

@@ -0,0 +1,31 @@
+// Copyright (c) 2023, Siemens AG
+//
+// SPDX-License-Identifier: MIT
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
+using Newtonsoft.Json.Serialization;
+
+namespace Siemens.Simatic.S7.Webserver.API.Enums
+{
+    /// <summary>
+    /// User Authentication modes of the PLC.<br/>
+    /// Depends on the configured user management which authentication modes will be supported by the PLC<br/>
+    /// based on the authentication mode.
+    /// </summary>
+    [JsonConverter(typeof(StringEnumConverter), converterParameters: typeof(SnakeCaseNamingStrategy))]
+    public enum ApiAuthenticationMode
+    {
+        /// <summary>
+        /// Legacy User Management
+        /// </summary>
+        Static,
+        /// <summary>
+        /// Only Anonymous user is available
+        /// </summary>
+        Disabled,
+        /// <summary>
+        /// The users are stored on the PLC
+        /// </summary>
+        Local
+    }
+}

src/Webserver.API/Enums/ApiBrowseFilterMode.cs

@@ -0,0 +1,27 @@
+// Copyright (c) 2023, Siemens AG
+//
+// SPDX-License-Identifier: MIT
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
+using System.Runtime.Serialization;
+
+namespace Siemens.Simatic.S7.Webserver.API.Enums
+{
+    /// <summary>
+    /// The mode if the attributes shall either be included or excluded.
+    /// </summary>
+    [JsonConverter(typeof(StringEnumConverter))]
+    public enum ApiBrowseFilterMode
+    {
+        /// <summary>
+        /// The response will include the listed attributes and exclude the others.
+        /// </summary>
+        [EnumMember(Value = "include")]
+        Include = 0,
+        /// <summary>
+        /// The response will exclude the listed attributes and include the others.
+        /// </summary>
+        [EnumMember(Value = "exclude")]
+        Exclude = 1,
+    }
+}

src/Webserver.API/Enums/ApiDayOfWeek.cs

@@ -0,0 +1,45 @@
+// Copyright (c) 2023, Siemens AG
+//
+// SPDX-License-Identifier: MIT
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
+using Newtonsoft.Json.Serialization;
+
+namespace Siemens.Simatic.S7.Webserver.API.Enums
+{
+    /// <summary>
+    /// Represents the days of the week
+    /// </summary>
+    [JsonConverter(typeof(StringEnumConverter), converterParameters: typeof(SnakeCaseNamingStrategy))]
+    public enum ApiDayOfWeek
+    {
+        /// <summary>
+        /// Sunday
+        /// </summary>
+        Sun = 1,
+        /// <summary>
+        /// Monday
+        /// </summary>
+        Mon = 2,
+        /// <summary>
+        /// Tuesday
+        /// </summary>
+        Tue = 3,
+        /// <summary>
+        /// Wednesday
+        /// </summary>
+        Wed = 4,
+        /// <summary>
+        /// Thursday
+        /// </summary>
+        Thu = 5,
+        /// <summary>
+        /// Friday
+        /// </summary>
+        Fri = 6,
+        /// <summary>
+        /// Saturday
+        /// </summary>
+        Sat = 7
+    }
+}

src/Webserver.API/Enums/ApiDiagnosticBufferBrowseFilterAttributes.cs

@@ -0,0 +1,32 @@
+// Copyright (c) 2023, Siemens AG
+//
+// SPDX-License-Identifier: MIT
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
+using System.Runtime.Serialization;
+
+namespace Siemens.Simatic.S7.Webserver.API.Enums
+{
+    /// <summary>
+    /// Possible filters for ApiDiagnosticBufferBrowse request
+    /// </summary>
+    [JsonConverter(typeof(StringEnumConverter))]
+    public enum ApiDiagnosticBufferBrowseFilterAttributes
+    {
+        /// <summary>
+        /// Filter for the short diagnostic buffer text.
+        /// </summary>
+        [EnumMember(Value = "short_text")]
+        ShortText = 1,
+        /// <summary>
+        /// Filter for the long diagnostic buffer text.
+        /// </summary>
+        [EnumMember(Value = "long_text")]
+        LongText = 2,
+        /// <summary>
+        /// Filter for the help text message in case of an incoming event.
+        /// </summary>
+        [EnumMember(Value = "help_text")]
+        HelpText = 3,
+    }
+}

src/Webserver.API/Enums/ApiErrorCode.cs

@@ -1,11 +1,6 @@
 // Copyright (c) 2023, Siemens AG
 //
 // SPDX-License-Identifier: MIT
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
 namespace Siemens.Simatic.S7.Webserver.API.Enums
 {
@@ -44,7 +39,7 @@ public enum ApiErrorCode
         /// The system does not have the necessary resources to execute the Web API request. 
         /// Execute the request again as soon as sufficient resources are available again.
         /// Some examples: you have
-        ///  -reached the limit for logins (depending on plc) - wait a maximum of 120 seconds and call the method (login) again.
+        ///  -reached the limit for logins (depending on plc) - wait 150 seconds and call the method (login) again.
         ///  -reached the limit for tickets for one user session or still a ticket for e.g. a download that is not closed yet. Close all open tickets in order to free resources and call this method again.
         ///  -system does generally not have the resources currently => wait for other requests to be completed
         /// Das System verfügt nicht über die nötigen Ressourcen, um den Web API-Request auszuführen 
@@ -58,6 +53,15 @@ public enum ApiErrorCode
         /// </summary>
         SystemIsReadOnly = 5,
         /// <summary>
+        /// The password change cannot be performed. This is caused for example if an older PLC project is present where password changes are not supported.
+        /// </summary>
+        PasswordChangeNotAccepted = 6,
+        /// <summary>
+        /// The data of a PLC of an R/H system is not accessible.
+        /// This may happen if the system is in state Syncup or RUN-redundant or if the service data of the partner PLC has been requested.
+        /// </summary>
+        PartnerNotAccessible = 7,
+        /// <summary>
         /// The given credentials dont match any downloaded credentials to the plc.
         /// </summary>
         LoginFailed = 100,
@@ -67,6 +71,18 @@ public enum ApiErrorCode
         /// </summary>
         AlreadyAuthenticated = 101,
         /// <summary>
+        /// The password of the user account has expired. The user needs to change the password to successfully authenticate again.
+        /// </summary>
+        PasswordExpired = 102,
+        /// <summary>
+        /// The provided new password does not match the required password policy.
+        /// </summary>
+        NewPasswordDoesNotFollowPolicy = 103,
+        /// <summary>
+        /// The provided new password is identical with the current password.
+        /// </summary>
+        NewPasswordMatchesOldPassword = 104,
+        /// <summary>
         /// The requested address does not exist or the webserver cannot access the requested address.
         /// Die angeforderte Adresse existiert nicht oder der Webserver kann nicht auf die angeforderte Adresse zugreifen.
         /// </summary>
@@ -176,10 +192,42 @@ public enum ApiErrorCode
         /// </summary>
         ResourceContentHasBeenCorrupted = 514,
         /// <summary>
+        /// Only one simultaneous ticket resource for service data across all users is possible at a time
+        /// </summary>
+        NoServiceDataResources = 600,
+        /// <summary>
+        /// The provided alarm ID is invalid.
+        /// </summary>
+        InvalidAlarmId = 800,
+        /// <summary>
+        /// The request is invalid. The user provided invalid parameters, e. g. alarm ID and count are present at the same time.
+        /// </summary>
+        InvalidAlarmsBrowseParameters = 801,
+        /// <summary>
+        /// The provided timestamp does not match the required timestamp format
+        /// </summary>
+        InvalidTimestamp = 900,
+        /// <summary>
+        /// The timestamp is not within the allowed range
+        /// </summary>
+        TimestampOutOfRange = 901,
+        /// <summary>
+        /// The provided rule is invalid. Check the DaylightSavingsRule object. If the Rule object is present, both DST and STD is required.
+        /// </summary>
+        InvalidTimeRule = 902,
+        /// <summary>
+        /// The provided UTC offset is invalid. Check the main utc offset, and the DaylightSavingsRule object's DST offset.
+        /// </summary>
+        InvalidUTCOffset = 903,
+        /// <summary>
         /// The PLC is not in operating mode stop. The method cannot be executed while the plc is not in stop mode.
         /// </summary>
         PLCNotInStop = 1004,
         /// <summary>
+        /// The requested hardware identifier is invalid
+        /// </summary>
+        InvalidHwId = 1100,
+        /// <summary>
         /// The method has not been found by the plc - check the spelling and fw-version (and according methods) of plc
         /// </summary>
         MethodNotFound = -32601,

src/Webserver.API/Enums/ApiFailsafeHardwareType.cs

@@ -0,0 +1,25 @@
+// Copyright (c) 2023, Siemens AG
+//
+// SPDX-License-Identifier: MIT
+using Newtonsoft.Json;
+using Newtonsoft.Json.Converters;
+using Newtonsoft.Json.Serialization;
+
+namespace Siemens.Simatic.S7.Webserver.API.Enums
+{
+    /// <summary>
+    /// The type defines if the requested hardware identifier represents either the safety PLC itself or another failsafe module.
+    /// </summary>
+    [JsonConverter(typeof(StringEnumConverter), converterParameters: typeof(SnakeCaseNamingStrategy))]
+    public enum ApiFailsafeHardwareType
+    {
+        /// <summary>
+        /// The hw id is a CPU
+        /// </summary>
+        F_cpu,
+        /// <summary>
+        /// The hw id is a module
+        /// </summary>
+        F_module
+    }
+}

src/Webserver.API/Enums/ApiFileResourceState.cs

@@ -1,9 +1,6 @@
 // Copyright (c) 2023, Siemens AG
 //
 // SPDX-License-Identifier: MIT
-using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace Siemens.Simatic.S7.Webserver.API.Enums
 {

src/Webserver.API/Enums/ApiFileResourceType.cs

@@ -1,9 +1,6 @@
 // Copyright (c) 2023, Siemens AG
 //
 // SPDX-License-Identifier: MIT
-using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace Siemens.Simatic.S7.Webserver.API.Enums
 {

src/Webserver.API/Enums/ApiObjectDirectoryStatus.cs

@@ -0,0 +1,21 @@
+// Copyright (c) 2023, Siemens AG
+//
+// SPDX-License-Identifier: MIT
+
+namespace Siemens.Simatic.S7.Webserver.API.Enums
+{
+    /// <summary>
+    /// The status of the entry. Either incoming or outgoing.
+    /// </summary>
+    public enum ApiObjectDirectoryStatus
+    {
+        /// <summary>
+        /// The entry is incoming
+        /// </summary>
+        Incoming = 1,
+        /// <summary>
+        /// The entry is outgoing
+        /// </summary>
+        Outgoing = 2
+    }
+}