Posh-UCS

2.5.9.2

UcsConfig.psm1

<###### UCS Configuration Utilities ######>

<#### PARAMETERS ####>
$Script:LocalStorageLocation = "$env:LOCALAPPDATA\UCS"
$Script:CredentialFileName = 'UcsCredential.xml'
$Script:ConfigFileName = 'UcsConfig.xml'
$Script:DisabledSuffix = '-disabled'
$Script:ConfigPath = Join-Path $Script:LocalStorageLocation $Script:ConfigFileName
$Script:CredentialPath = Join-Path $Script:LocalStorageLocation $Script:CredentialFileName
$Script:ImportedConfigInUse = $false
$Script:ImportedCredentialInUse = $false

# Storage initilization at end, after function definitions.

<#### Function definitions ####>

<## INTERNAL ##>
Function New-UcsConfig
{
  <#
      .NOTES
      For internal use only - used to create initial config objects.
 
      .PARAMETER Priority
      The item with the lowest numerical value priority goes first in order. In case of a tie, APIs are ranked alphabetically.
  #>
  Param (
    [Parameter(Mandatory,ValueFromPipelineByPropertyName,ValueFromPipeline)][ValidateSet('REST','SIP','Poll','Push','Web','Provisioning')][String]$API,
    [Nullable[Timespan]]$Timeout = (New-TimeSpan -Seconds 3),
    [Nullable[Int]][ValidateRange(1,100)]$Retries = 2,
    [Nullable[Int]][ValidateRange(0,65535)]$Port = 80,
    [Nullable[bool]]$EnableEncryption = $false,
    [Nullable[Int]]$Priority = 50,
    [Nullable[bool]]$Enabled = $true
  )

  if($Timeout.TotalSeconds -le 0)
  {
    Write-Error "Couldn't create options because timeout was set to 0 or less." -ErrorAction Stop -Category InvalidArgument
  }

  $OutputObject = $API | Select-Object @{Name='API';Expression={$API}},
    @{Name='Timeout';Expression={$Timeout}},
    @{Name='Retries';Expression={$Retries}},
    @{Name='Port';Expression={$Port}},
    @{Name='EnableEncryption';Expression={$EnableEncryption}},
    @{Name='Priority';Expression={$Priority}},
    @{Name='Enabled';Expression={$Enabled}}

  Return $OutputObject
}

Function Get-UcsConfig
{
  Param (
    [Parameter(Mandatory,ValueFromPipelineByPropertyName,ValueFromPipeline)][ValidateSet('REST','SIP','Poll','Push','Web','Provisioning')][String]$API
  )

  $RequestedConfig = $Script:MasterConfig | Where-Object -Property API -EQ -Value $API

  Return $RequestedConfig
}

Function Get-UcsConfigPriority
{
  $AllConfigs = $Script:MasterConfig
  $EnabledConfigs = $AllConfigs | Where-Object -Property Enabled -EQ -Value $true
  $SortedConfigs = $EnabledConfigs | Sort-Object -Property Priority,API
  $SortedConfigNames = $SortedConfigs | Select-Object -ExpandProperty API

  Return $SortedConfigNames
}

Function Set-UcsConfig
{
  Param (
    [Parameter(Mandatory,ValueFromPipelineByPropertyName,ValueFromPipeline)][ValidateSet('REST','SIP','Poll','Push','Web','Provisioning')][String]$API,
    [Nullable[Timespan]]$Timeout = $null,
    [Nullable[Int]][ValidateRange(1,100)]$Retries = $null,
    [Nullable[Int]][ValidateRange(0,65535)]$Port = $null,
    [Nullable[bool]]$EnableEncryption = $null,
    [Nullable[Int]]$Priority = $null,
    [Nullable[bool]]$Enabled = $null
  )

  Process
  {
      $WorkingConfig = Get-UcsConfig -API $API

      if($null -ne $Retries)
      {
        $WorkingConfig.Retries = $Retries
      }

      if($null -ne $Timeout)
      {
        if($Timeout.TotalSeconds -lt 0)
        {
          Write-Error "Couldn't create options because timeout was set to less than 0." -ErrorAction Stop -Category InvalidArgument
        }
        else
        {
          $WorkingConfig.Timeout = $Timeout
        }
      }

      if($null -ne $Port)
      {
        $WorkingConfig.Port = $Port
      }

      if($null -ne $EnableEncryption)
      {
        if($null -eq $WorkingConfig.EnableEncryption)
        {
          Write-Error ('Encryption is not supported by the {0} API.' -f $API)
        }
        else
        {
          $WorkingConfig.EnableEncryption = $EnableEncryption
        }
      }

      if($null -ne $Priority)
      {
        $MatchingPriority = $Script:MasterConfig | Where-Object -Property Priority -eq $Priority | Measure-Object
        if($MatchingPriority.Count -gt 0)
        {
          Write-Warning ('Cannot set priority of {0} to {1} because that priority level is in use on one or more other APIs.' -f $WorkingConfig.API,$Priority)
        }
        else
        {
          $WorkingConfig.Priority = $Priority
        }
      }

      if($null -ne $Enabled)
      {
        $WorkingConfig.Enabled = $Enabled
      }

      Foreach($Configuration in $Script:MasterConfig)
      {
        if($Configuration.API -eq $API)
        {
         $Configuration = $WorkingConfig
        }
      }
  }
  End
  {
     Update-UcsConfigStorage
  }
}

Function New-UcsConfigCredential
{
  Param (
    [Parameter(Mandatory,ValueFromPipelineByPropertyName,ValueFromPipeline)][ValidateSet('REST','Poll','Push','Web')][String]$API,
    [Parameter(Mandatory)][PSCredential]$Credential,
    [String]$DisplayName = '',
    [Int]$Priority = 50,
    [String]$Identity = '*',
    [Boolean]$Enabled = $true
  )

  $OutputObject = $API | Select-Object @{Name='API';Expression={$API}},
    @{Name='Identity';Expression={$Identity}},
    @{Name='DisplayName';Expression={$DisplayName}},
    @{Name='Credential';Expression={$Credential}},
    @{Name='Priority';Expression={$Priority}},
    @{Name='Enabled';Expression={$Enabled}}


  Add-UcsConfigCredential $OutputObject
}

Function New-UcsConfigCredentialPlaintext
{
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", 'Password',
    Justification='This cmdlet takes a plaintext password and converts it to SecureString.')]
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingUserNameAndPassWordParams", '',
    Justification='This cmdlet takes a plaintext password and converts it to SecureString.')]
  Param (
    [Parameter(Mandatory)][String]$Username,
    [Parameter(Mandatory)][String]$Password
  )

  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingConvertToSecureStringWithPlainText", '',
    Scope='Function')] #TODO: This doesn't successfully suppress the error. Why?
  $SecureStringPassword = ConvertTo-SecureString -String $Password -AsPlainText -Force
  $Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList ($Username,$SecureStringPassword)

  Return $Credential
}

Function Get-UcsConfigCredential
{
  Param (
    [Parameter(Mandatory,ValueFromPipelineByPropertyName,ValueFromPipeline)][ValidateSet('REST','Poll','Push','Web')][String]$API,
    [Switch]$IncludeDisabled,
    [Switch]$CredentialOnly
  )

  $AllCredentials = $Script:MasterCredentials

  if(!$IncludeDisabled)
  {
    $AllCredentials = $AllCredentials | Where-Object -Property Enabled -EQ -Value $true
  }

  $ThisAPICredentials = $AllCredentials | Where-Object -Property API -EQ -Value $API
  $SortedCredentials = $ThisAPICredentials | Sort-Object -Property Priority,API,Index

  if($CredentialOnly)
  {
    Return $SortedCredentials.Credential
  }
  else
  {
    Return $SortedCredentials
  }
}

Function Add-UcsConfigCredential
{
  [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", 'UcsConfigCredential',
  Justification='The type of object this accepts contains a PsCredential object.')]
  Param (
    [Parameter(Mandatory)][Object]$UcsConfigCredential
  )
  Process
  {
      if($UcsConfigCredential.Credential.GetType().Name -ne 'PSCredential' -or $null -eq $UcsConfigCredential.Priority)
      {
        Write-Error "Invalid UcsConfigCredential supplied."
      }

      $HighestIndex = $Script:MasterCredentials | Sort-Object -Property Index -Descending `
        | Select-Object -First 1 | Select-Object -ExpandProperty Index
      $ThisIndex = $HighestIndex + 1

      $IndexRemoved = $UcsConfigCredential | Select-Object -Property * -ExcludeProperty Index
      $CredentialToSave = $IndexRemoved | Select-Object -Property *,@{Name='Index';Expression={$ThisIndex}}

      $null = $Script:MasterCredentials.Add($CredentialToSave)
  }
  End
  {
    Update-UcsConfigCredentialStorage
  }
}

Function Remove-UcsConfigCredential
{
  Param (
    [Parameter(Mandatory,ValueFromPipelineByPropertyName)][Int[]]$Index
  )

  Process
  {
    Foreach($ThisIndex in $Index)
    {
      #We must rebuild the arraylist because doing a simple filter on the arraylist turns it into a collection of fixed size.
      $NewMasterCredentials = New-Object Collections.ArrayList
      Foreach($Credential in $Script:MasterCredentials)
      {
        if($Credential.Index -ne $ThisIndex)
        {
          $null = $NewMasterCredentials.Add($Credential)
        }
      }
    }
  }
  End
  {
    $Script:MasterCredentials = $NewMasterCredentials
    Update-UcsConfigCredentialStorage
  }
}

Function Set-UcsConfigCredential
{
   Param (
    [Parameter(Mandatory,ValueFromPipelineByPropertyName)][Int[]]$Index,
    [AllowEmptyString()][ValidateSet('REST','Poll','Push','Web')][String]$API = '',
    [PsCredential]$Credential = $null,
    [String]$DisplayName = '',
    [Nullable[Int]]$Priority = $null,
    [String]$Identity = '',
    [Nullable[Boolean]]$Enabled = $null
  )

  Process
  {
    Foreach($ThisIndex in $Index)
    {
      $WorkingCredential = $Script:MasterCredentials | Where-Object -Property Index -EQ -Value $ThisIndex

      if($null -eq $WorkingCredential)
      {
        Write-Error "Invalid index $ThisIndex."
        Continue
      }

      if($API.Length -gt 0)
      {
        $WorkingCredential.API = $API
      }

      if($null -ne $Credential)
      {
        if($Credential.GetType().Name -eq 'PSCredential')
        {
          $WorkingCredential.Credential = $Credential
        }
      }

      if($DisplayName.Length -gt 0)
      {
        $WorkingCredential.DisplayName = $DisplayName
      }

      if($null -ne $Priority)
      {
        $WorkingCredential.Priority = $Priority
      }

      if($Identity.Length -gt 0)
      {
        $WorkingCredential.Identity = $Identity
      }

      if($null -ne $Enabled)
      {
        $WorkingCredential.Enabled = $Enabled
      }

      Foreach($Credential in $Script:MasterCredentials)
      {
        if($Credential.Index -eq $ThisIndex)
        {
          $Credential = $WorkingCredential
          Break
        }
      }
    }
  }
  End
  {
    Update-UcsConfigCredentialStorage
  }
}


<## Config storage ##>
Function Import-UcsConfigStorage
{
  Param (
    [String]$Path = $Script:ConfigPath
  )

  if((Test-Path $Path) -eq $false)
  {
    Write-Error "Could not find file at $Path." -ErrorAction Stop
  }

  Write-Debug "Importing $Path to UcsConfig."
  $Imported = Import-Clixml -Path $Path

  $Script:MasterConfig = $Imported
  $Script:ImportedConfigInUse = $true
}

Function Update-UcsConfigStorage
{
  Param (
    [String]$Path = $Script:ConfigPath
  )

  $Directory = Split-Path $Path

  if( (Test-Path $Directory) -eq $false)
  {
    Write-Debug "Path $Directory not found. Creating..."
    $null = New-Item -Path $Directory -ItemType Directory -Force
  }

  if($Script:ImportedConfigInUse)
  {
    Write-Debug "Writing XML file to $Path."
    $Script:MasterConfig | Export-Clixml -Path $Path -Depth 1
  }
  else
  {
    Write-Debug "Imported config not currently in use, not updating."
  }
}

Function Enable-UcsConfigStorage
{
   [CmdletBinding(SupportsShouldProcess,ConfirmImpact = 'High')]
   Param()

   if($Script:ImportedConfigInUse -eq $true)
   {
    Write-Error "Config storage already in use."
    Break
   }

   if($PSCmdlet.ShouldProcess($Script:ConfigPath))
   {
     $Script:ImportedConfigInUse = $true
     Update-UcsConfigStorage
   }
}

Function Disable-UcsConfigStorage
{
   [CmdletBinding(SupportsShouldProcess,ConfirmImpact = 'High')]
   Param()

   if($Script:ImportedConfigInUse -ne $true)
   {
    Write-Error "Config storage not in use."
    Break
   }

   if($PSCmdlet.ShouldProcess($Script:ConfigPath))
   {
     $Script:ImportedConfigInUse = $false
     $ThisItem = Get-Item -Path $Script:ConfigPath
     $NewName = ('{0}{1}{2}' -f $ThisItem.BaseName,$Script:DisabledSuffix,$ThisItem.Extension)
     $NewPath = Join-Path $ThisItem.Directory $NewName
     $null = Rename-Item -Path $Script:ConfigPath -NewName $NewPath -Force
   }
}

Function Get-UcsConfigStorageIsEnabled
{
  Return $Script:ImportedConfigInUse
}

<## Credential storage ##>
Function Import-UcsConfigCredentialStorage
{
  Param (
    [String]$Path = $Script:CredentialPath
  )

  if((Test-Path $Path) -eq $false)
  {
    Write-Error "Could not find file at $Path." -ErrorAction Stop
  }

  Write-Debug "Importing $Path to UcsConfig."
  $Imported = Import-Clixml -Path $Path

  $Script:MasterCredentials = New-Object Collections.ArrayList
  Foreach($Cred in $Imported)
  {
    $null = $Script:MasterCredentials.Add($Cred)
  }

  $Script:ImportedCredentialInUse = $true
}

Function Update-UcsConfigCredentialStorage
{
  Param (
    [String]$Path = $Script:CredentialPath
  )

  $Directory = Split-Path $Path

  if( (Test-Path $Directory) -eq $false)
  {
    Write-Debug "Path $Directory not found. Creating..."
    $null = New-Item -Path $Directory -ItemType Directory -Force
  }

  if($Script:ImportedCredentialInUse)
  {
    Write-Debug "Writing XML file to $Path."
    $Script:MasterCredentials | Export-Clixml -Path $Path -Depth 1
  }
  else
  {
    Write-Debug "Imported credentials not currently in use, not updating."
  }
}

Function Enable-UcsConfigCredentialStorage
{
   [CmdletBinding(SupportsShouldProcess,ConfirmImpact = 'High')]
   Param()

   if($Script:ImportedCredentialInUse -eq $true)
   {
    Write-Error "Credential storage already in use."
    Break
   }

   if($PSCmdlet.ShouldProcess($Script:CredentialPath))
   {
     $Script:ImportedCredentialInUse = $true
     Update-UcsConfigCredentialStorage
   }
}

Function Disable-UcsConfigCredentialStorage
{
   [CmdletBinding(SupportsShouldProcess,ConfirmImpact = 'High')]
   Param()

   if($Script:ImportedCredentialInUse -ne $true)
   {
    Write-Error "Credential storage not in use."
    Break
   }

   if($PSCmdlet.ShouldProcess($Script:CredentialPath))
   {
     $Script:ImportedCredentialInUse = $false
     $ThisItem = Get-Item -Path $Script:CredentialPath
     $NewName = ('{0}{1}{2}' -f $ThisItem.BaseName,$Script:DisabledSuffix,$ThisItem.Extension)
     $NewPath = Join-Path $ThisItem.Directory $NewName
     $null = Rename-Item -Path $Script:CredentialPath -NewName $NewPath -Force
   }
}
Function Get-UcsConfigCredentialStorageIsEnabled
{
  Return $Script:ImportedCredentialInUse
}

<#### Create Credential Storage ####>
$Script:MasterCredentials = New-Object Collections.ArrayList

<#### Initialize default credentials ####>
New-UcsConfigCredential -API REST -Credential (New-UcsConfigCredentialPlaintext -Username 'Polycom' -Password '456') -DisplayName "Polycom default REST credential" -Priority 1000
New-UcsConfigCredential -API Web -Credential (New-UcsConfigCredentialPlaintext -Username 'Polycom' -Password '456') -DisplayName "Polycom default Web credential" -Priority 1000
New-UcsConfigCredential -API Poll -Credential (New-UcsConfigCredentialPlaintext -Username 'UCSToolkit' -Password 'UCSToolkit') -DisplayName "Script default Polling credential" -Priority 1000
New-UcsConfigCredential -API Push -Credential (New-UcsConfigCredentialPlaintext -Username 'UCSToolkit' -Password 'UCSToolkit') -DisplayName "Script default Push credential" -Priority 1000

<#### Define defaults for configs ####>
$Script:MasterConfig = (
  (New-UcsConfig -API REST -Timeout (New-TimeSpan -Seconds 2) -Retries 1 -Port 80 -EnableEncryption $false -Priority 1 -Enabled $true),
  (New-UcsConfig -API SIP -Timeout (New-TimeSpan -Seconds 5) -Retries 2 -Port 5060 -EnableEncryption $null -Priority 90 -Enabled $true),
  (New-UcsConfig -API Poll -Timeout (New-TimeSpan -Seconds 2) -Retries 2 -Port 80 -EnableEncryption $null -Priority 30 -Enabled $true),
  (New-UcsConfig -API Push -Timeout (New-TimeSpan -Seconds 2) -Retries 2 -Port 80 -EnableEncryption $false -Priority 40 -Enabled $true),
  (New-UcsConfig -API Web -Timeout (New-TimeSpan -Seconds 2) -Retries 2 -Port 80 -EnableEncryption $null -Priority 20 -Enabled $true),
  (New-UcsConfig -API Provisioning -Timeout (New-TimeSpan -Seconds 5) -Retries 1 -Port 0 -EnableEncryption $null -Priority 100 -Enabled $true)
)

<#### Check for preferences ####>
if( Test-Path $Script:ConfigPath )
{
  Write-Debug "Found config file at $Script:ConfigPath."
  Import-UcsConfigStorage
}

if( Test-Path $Script:CredentialPath )
{
  Write-Debug "Found credential file at $Script:CredentialPath."
  Import-UcsConfigCredentialStorage
}