<#
.SYNOPSIS
Broadcast one or more "magic packets" across a subnet to wake-up one or more target computers.

.DESCRIPTION
Sends two (2) "magic packets" spaced one (1) second apart per supplied MAC address as a broadcast over the subnet using a specified UDP port. MAC addresses can be supplied directly or via the pipeline either with or without explicitly specifying a parameter. The broadcast address and UDP port can be specified via parameters.

Note: You must specify the '-Verbose' parameter to see output for successfully sent packets.

.PARAMETER MacAddress
Array of MAC addresses for which to construct magic packets. The array should be provided in standard comma-separated string format ('1a:2a:3a:4a:5a:aa', '1b:2b:3b:4b:5b:bb', ...). You may use either a colon (:) or a hyphen (-) to delimit each hex value-pair in the MAC address. You may supply this array either directly or via the pipline.

.PARAMETER BroadcastIP
The address to which magic packets should be sent in order for them to be broadcast across the subnet. By default this is 255.255.255.255 however, many routers block such global broadcasts. Therefore, it is suggested to use the subnet-specific broadcast address (e.g. 192.168.1.255). You may also use IP6 multicast addresses (ff02::1 may work in your environment) if you prefer.

.PARAMETER Port
The UDP port that should be used when sending the broadcast. By default this is port 7 (echo). Port 9 (discard) is also a common port.

.INPUTS
String array or object containing a string array named "MacAddress".

.EXAMPLE
Send-MagicPacket 1a-2a-3a-4a-5a-aa
Wake-up a computer with MAC address '1a-2a-3a-4a-5a-aa' via global broadcast using default port (echo).

.EXAMPLE
Send-MagicPacket '1a-2a-3a-4a-5a-aa' 192.168.1.255 9
Wake-up a computer with MAC address '1a-2a-3a-4a-5a-aa' in subnet 192.168.1.0/24 using port 9 (discard).

.EXAMPLE
Send-MagicPacket -MacAddress '1a-2a-3a-4a-5a-aa', '1b-2b-3b-4b-5b-bb', '1c:2c:3c:4c:5c:cc' -Port 99 -BroadcastIP 10.0.1.255 -Verbose
Wake-up 3 computers in the specified subnet using non-standard port. Parameters are explicitly defined. Show confirmation messages for each MAC address.

.EXAMPLE
'1a-2a-3a-4a-5a-aa', '1b-2b-3b-4b-5b-bb' | Send-MagicPacket -IP 172.16.20.255 -Verbose
Use pipeline to provide MAC addresses, provide broadcast address directly. Show result.

.NOTES
There is no output generated for successfully sent packets. This is done to keep the pipeline clear. To see success confirmation messages, run this function with the '-Verbose' parameter.
#>
function Send-MagicPacket
{
    [CmdletBinding()]
    param
    (
    # Array of MAC addresses for which to construct magic packets
        [Parameter(
                Mandatory,
                ValueFromPipeline,
                ValueFromPipelineByPropertyName,
                HelpMessage = "Please provide one or more MAC addresses. You may use a colon (:) or a hypen (-) to separate hex values."
        )]
        [String[]]
        $MacAddress,

    # Broadcast IP address (default: all subnets --> 255.255.255.255)
        [Alias("IP", "Address")]
        [Parameter()]
        [IPAddress]
        $BroadcastIP = [System.Net.IPAddress]::Broadcast,

    # UDP port over which to broadcast magic packet (default: 7)
        [Parameter()]
        [Int16]
        $Port = 7
    )

    begin
    {
        # instantiate UDP client
        try
        {
            $UdpClient = [System.Net.Sockets.UdpClient]::new()
        }
        catch
        {
            Write-Error "Unable to instantiate UDP Client to send magic packets"
        }
    }

    process
    {
        foreach ($addr in $MacAddress)
        {
            # validate MAC address format or write error and continue
            if (!($addr -match '^([0-9A-F]{2}[:-]){5}([0-9A-F]{2})$'))
            {
                Write-Error "Invalid MAC address: $addr"
                continue
            }

            # convert MAC address to magic packet
            try
            {
                # construct byte-array from MAC address
                $MAC = $addr -split '[:-]' | ForEach-Object {
                    [Byte]"0x$_"
                }

                # construct magic packet
                # first 6 bytes = FF (255) then repeat MAC address 16 times
                [Byte[]]$magicPacket = (,0xFF * 6) + ($MAC * 16)
            }
            catch
            {
                Write-Error "Unable to process MAC address: $thisMacAddress"
                continue
            }

            # broadcast magic packets
            try
            {
                $UdpClient.Connect($BroadcastIP, $Port)
                $UdpClient.Send($magicPacket, $magicPacket.Length) | Out-Null
                Start-Sleep -Seconds 1
                $UdpClient.Send($magicPacket, $magicPacket.Length) | Out-Null
                Write-Verbose "Sent magic packet: Broadcast $addr over $BroadcastIP on port $Port (UDP)"
            }
            catch
            {
                Write-Error "Unable to send magic packet for '$addr'"
                continue
            }
        }
    }

    end
    {
        # dispose of UDP client
        $UdpClient.Close()
        $UdpClient.Dispose()
    }
}

Export-ModuleMember -Function Send-MagicPacket