Merge pull request #32 from pyrocumulus/post-system-service

Add PostSystem request

CHANGELOG.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Unreleased
 
 - Added SearchService.SearchByPostCodeOrSize, a method to search for both parameters at the same time [#31](https://github.com/pyrocumulus/pvoutput.net/pull/31)
+- Added SystemService.PostSystem, enabling the modification of a system's name and/or extended value [#32](https://github.com/pyrocumulus/pvoutput.net/pull/32)
 
 ## [0.7.0] - 2020-04-08
 

src/PVOutput.Net/Builders/ExtendedDataDefinitionBuilder.cs

@@ -0,0 +1,159 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using Dawn;
+using PVOutput.Net.Enums;
+using PVOutput.Net.Objects;
+using PVOutput.Net.Objects.Modules.Implementations;
+
+namespace PVOutput.Net.Builders
+{
+    /// <summary>
+    /// Builder for creating extended data definitions, used to update systems.
+    /// </summary>
+    public sealed class ExtendedDataDefinitionBuilder
+    {
+        internal ExtendedDataDefinition _definition;
+
+        /// <summary>
+        /// Creates a new builder.
+        /// </summary>
+        public ExtendedDataDefinitionBuilder()
+        {
+            _definition = new ExtendedDataDefinition();
+        }
+
+        /// <summary>
+        /// The index that specifies which extended data value to update.
+        /// </summary>
+        /// <param name="index">The index of the extended data value.</param>
+        /// <returns>The builder.</returns>
+        public ExtendedDataDefinitionBuilder SetIndex(ExtendedDataIndex index)
+        {
+            _definition.Index = index;
+            return this;
+        }
+
+        /// <summary>
+        /// Sets the label of the extended data value.
+        /// </summary>
+        /// <param name="label">The label to set.</param>
+        /// <returns>The builder.</returns>
+        public ExtendedDataDefinitionBuilder SetLabel(string label)
+        {
+            Guard.Argument(label).MaxLength(20);
+
+            _definition.Label = label;
+            return this;
+        }
+
+        /// <summary>
+        /// Sets the unit of the extended data value.
+        /// </summary>
+        /// <param name="unit">The unit to set.</param>
+        /// <returns>The builder.</returns>
+        public ExtendedDataDefinitionBuilder SetUnit(string unit)
+        {
+            Guard.Argument(unit).MaxLength(10);
+
+            _definition.Unit = unit;
+            return this;
+        }
+
+        /// <summary>
+        /// Sets the displayed colour of the extended data value.
+        /// </summary>
+        /// <param name="colour">Hexadecimal colour to display <c>6 hexadecimal characters</c>.</param>
+        /// <returns>The builder.</returns>
+        public ExtendedDataDefinitionBuilder SetColour(string colour)
+        {
+            Guard.Argument(colour).Length(6);
+            Guard.Argument(colour).Require(IsHexadecimalString, m => "Colour should be a hexadecimal string.");
+
+            _definition.Colour = colour;
+            return this;
+        }
+
+        /// <summary>
+        /// Sets the axis used to display the extended data value on.
+        /// </summary>
+        /// <param name="axis">The axis to display the extended data value on.</param>
+        /// <returns>The builder</returns>
+        public ExtendedDataDefinitionBuilder SetAxis(int axis)
+        {
+            Guard.Argument(axis).InRange(0, 5);
+
+            _definition.Axis = axis;
+            return this;
+        }
+
+        /// <summary>
+        /// Sets the graph type used to display the extended data value.
+        /// </summary>
+        /// <param name="displayType">Display type to use.</param>
+        /// <returns>The builder.</returns>
+        public ExtendedDataDefinitionBuilder SetDisplayType(ExtendedDataDisplayType displayType)
+        {
+            _definition.DisplayType = displayType;
+            return this;
+        }
+
+        /// <summary>
+        /// Uses information within the builder to return the built data definition.
+        /// </summary>
+        /// <returns>The extended data definition.</returns>
+        public IExtendedDataDefinition Build()
+        {
+            return _definition;
+        }
+
+        /// <summary>
+        /// Uses information within the builder to return the built data definition.
+        /// Resets the builder to it's default state after building.
+        /// </summary>
+        /// <returns>The extended data definition.</returns>
+        public IExtendedDataDefinition BuildAndReset()
+        {
+            var result = _definition;
+            _definition = new ExtendedDataDefinition();
+            return result;
+        }
+
+        /// <summary>
+        /// Resets the builder to it's default state. Ready to build a new definition.
+        /// </summary>
+        /// <returns>The builder in it's default state.</returns>
+        public ExtendedDataDefinitionBuilder Reset()
+        {
+            _definition = new ExtendedDataDefinition();
+            return this;
+        }
+
+        internal static bool IsHexadecimalString(string colour)
+        {
+            foreach (char character in colour.ToUpperInvariant())
+            {
+                if (!IsHexadecimalCharacter(character))
+                {
+                    return false;
+                }
+            }
+            return true;
+        }
+
+        internal static bool IsHexadecimalCharacter(char character)
+        {
+            if (character >= '0' && character <= '9')
+            {
+                return true;
+            }
+
+            if (character >= 'A' && character <= 'F')
+            {
+                return true;
+            }
+
+            return false;
+        }
+    }
+}

src/PVOutput.Net/Enums/ExtendedDataDisplayType.cs

@@ -0,0 +1,18 @@
+namespace PVOutput.Net.Enums
+{
+    /// <summary>
+    /// Defines how to display the extended value.
+    /// </summary>
+    public enum ExtendedDataDisplayType
+    {
+        /// <summary>
+        /// Display as line in graph.
+        /// </summary>
+        Line,
+
+        /// <summary>
+        /// Display as area in graph.
+        /// </summary>
+        Area
+    }
+}

src/PVOutput.Net/Enums/ExtendedDataIndex.cs

@@ -0,0 +1,43 @@
+using System;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Text;
+
+namespace PVOutput.Net.Enums
+{
+    /// <summary>
+    /// Describes the index of an extended data value.
+    /// </summary>
+    public enum ExtendedDataIndex
+    {
+        /// <summary>
+        /// Extended data value v7.
+        /// </summary>
+        v7,
+
+        /// <summary>
+        /// Extended data value v8.
+        /// </summary>
+        v8,
+
+        /// <summary>
+        /// Extended data value v9.
+        /// </summary>
+        v9,
+
+        /// <summary>
+        /// Extended data value v10.
+        /// </summary>
+        v10,
+
+        /// <summary>
+        /// Extended data value v11.
+        /// </summary>
+        v11,
+
+        /// <summary>
+        /// Extended data value v12.
+        /// </summary>
+        v12
+    }
+}

src/PVOutput.Net/Modules/OutputService.cs

@@ -3,6 +3,7 @@
 using System.Threading;
 using System.Threading.Tasks;
 using Dawn;
+using PVOutput.Net.Builders;
 using PVOutput.Net.Enums;
 using PVOutput.Net.Objects;
 using PVOutput.Net.Objects.Core;
@@ -148,6 +149,7 @@ public Task<PVOutputArrayResponse<IAggregatedOutput>> GetAggregatedOutputsAsync(
         /// <summary>
         /// Adds a single daily output to the owned system.
         /// <para>See the official <see href="https://pvoutput.org/help.html#api-addoutput">API information</see>.</para>
+        /// Use the <see cref="OutputPostBuilder"/> to create <see cref="IOutputPost"/> objects.
         /// </summary>
         /// <param name="output">The output to add.</param>
         /// <param name="cancellationToken">A cancellation token for the request.</param>
@@ -168,6 +170,7 @@ public Task<PVOutputBasicResponse> AddOutputAsync(IOutputPost output, Cancellati
         /// <summary>
         /// Adds a list of outputs to the owned system.
         /// <para>See the official <see href="https://pvoutput.org/help.html#api-addbatchoutput">API information</see>.</para>
+        /// Use the <see cref="BatchOutputPostBuilder"/> to create <see cref="IBatchOutputPost"/> objects.
         /// </summary>
         /// <param name="outputs">Outputs to add. 30 outputs is the maximum, 100 for donation</param>
         /// <param name="cancellationToken">A cancellation token for the request.</param>

src/PVOutput.Net/Modules/StatusService.cs

@@ -3,6 +3,7 @@
 using System.Threading;
 using System.Threading.Tasks;
 using Dawn;
+using PVOutput.Net.Builders;
 using PVOutput.Net.Objects;
 using PVOutput.Net.Objects.Core;
 using PVOutput.Net.Requests.Handler;
@@ -101,6 +102,7 @@ public Task<PVOutputResponse<IDayStatistics>> GetDayStatisticsForPeriodAsync(Dat
         /// <summary>
         /// Adds a single status to the owned system.
         /// <para>See the official <see href="https://pvoutput.org/help.html#api-addstatus">API information</see>.</para>
+        /// Use the <see cref="StatusPostBuilder{IStatusPost}"/> to create <see cref="IStatusPost"/> objects.
         /// </summary>
         /// <param name="status">The status to add.</param>
         /// <param name="cancellationToken">A cancellation token for the request.</param>
@@ -121,6 +123,7 @@ public Task<PVOutputBasicResponse> AddStatusAsync(IStatusPost status, Cancellati
         /// <summary>
         /// Adds multiple statuses to the owned system.
         /// <para>See the official <see href="https://pvoutput.org/help.html#api-addbatchstatus">API information</see>.</para>
+        /// Use the <see cref="StatusPostBuilder{IBatchStatusPost}"/> to create <see cref="IBatchStatusPost"/> objects.
         /// </summary>
         /// <param name="statuses">The statuses to add.</param>
         /// <param name="cancellationToken">A cancellation token for the request.</param>

src/PVOutput.Net/Modules/SystemService.cs

@@ -1,6 +1,9 @@
 using System.Collections.Generic;
+using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Tasks;
+using Dawn;
+using PVOutput.Net.Builders;
 using PVOutput.Net.Objects;
 using PVOutput.Net.Objects.Core;
 using PVOutput.Net.Requests.Handler;
@@ -54,5 +57,29 @@ public Task<PVOutputResponse<ISystem>> GetOtherSystemAsync(int systemId, Cancell
             var handler = new RequestHandler(Client);
             return handler.ExecuteSingleItemRequestAsync<ISystem>(new SystemRequest { SystemId = systemId, MonthlyEstimates = false }, loggingScope, cancellationToken);
         }
+
+        /// <summary>
+        /// Updates a system's name or extended data values. 
+        /// Use the <see cref="ExtendedDataDefinitionBuilder"/> to create definition for extended data values.
+        /// <para>See the official <see href="https://pvoutput.org/help.html#api-postsystem">API information</see>.</para>
+        /// </summary>
+        /// <param name="systemId">The system to update.</param>
+        /// <param name="systemName">A new name for the system.</param>
+        /// <param name="dataDefinitions">List of modified extended data definitions.</param>
+        /// <param name="cancellationToken">A cancellation token for the request.</param>
+        /// <returns>If the operation succeeded.</returns>
+        public Task<PVOutputBasicResponse> PostSystem(int systemId, string systemName = null, IEnumerable<IExtendedDataDefinition> dataDefinitions = null, CancellationToken cancellationToken = default)
+        {
+            var loggingScope = new Dictionary<string, object>()
+            {
+                [LoggingEvents.RequestId] = LoggingEvents.SystemService_PostSystem,
+                [LoggingEvents.Parameter_SystemId] = systemId
+            };
+
+            Guard.Argument(systemName).MaxLength(30);
+
+            var handler = new RequestHandler(Client);
+            return handler.ExecutePostRequestAsync(new PostSystemRequest() { SystemId = systemId, SystemName = systemName, DataDefinitions = dataDefinitions }, loggingScope, cancellationToken);
+        }
     }
 }

src/PVOutput.Net/Objects/Core/LoggingEvents.cs

@@ -96,6 +96,7 @@ internal class LoggingEvents
 
         public const int SystemService_GetOwnSystem = 21001;
         public const int SystemService_GetOtherSystem = 21002;
+        public const int SystemService_PostSystem = 21003;
 
         public const int TeamService_GetTeam = 21101;
         public const int TeamService_JoinTeam = 21102;

src/PVOutput.Net/Objects/IExtendedDataDefinition.cs

@@ -0,0 +1,43 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using PVOutput.Net.Enums;
+
+namespace PVOutput.Net.Objects
+{
+    /// <summary>
+    /// Defines an extended data value for a system.
+    /// </summary>
+    public interface IExtendedDataDefinition
+    {
+        /// <summary>
+        /// The index of the extended data value (v7-v12).
+        /// </summary>
+        ExtendedDataIndex Index { get; set; }
+
+        /// <summary>
+        /// The label of the extended data value.
+        /// </summary>
+        string Label { get; set; }
+
+        /// <summary>
+        /// The unit of the extended data value.
+        /// </summary>        
+        string Unit { get; set; }
+
+        /// <summary>
+        /// The hexadecimal colour (ffffff) used to display the extended data value.
+        /// </summary>
+        string Colour { get; set; }
+
+        /// <summary>
+        /// The axis on which to display the extended data value.
+        /// </summary>
+        int? Axis { get; set; }
+
+        /// <summary>
+        /// The type of graph to display the extended data value with.
+        /// </summary>
+        ExtendedDataDisplayType? DisplayType { get; set; }
+    }
+}

src/PVOutput.Net/Objects/Modules/Implementations/ExtendedDataDefinition.cs

@@ -0,0 +1,17 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+using PVOutput.Net.Enums;
+
+namespace PVOutput.Net.Objects.Modules.Implementations
+{
+    internal class ExtendedDataDefinition : IExtendedDataDefinition
+    {
+        public ExtendedDataIndex Index { get; set; }
+        public string Label { get; set; }
+        public string Unit { get; set; }
+        public string Colour { get; set; }
+        public int? Axis { get; set; }
+        public ExtendedDataDisplayType? DisplayType { get; set; }
+    }
+}