Functions/New-WmiFilterToConsumerBinding.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
# TODO: Test creation of a new __FilterToConsumerBinding instance against a remote computer
# TODO: Rename this cmdlet to New-WmiEventBinding for consistency?

<#
    .Synopsis
    Creates a new binding between a WMI event filter and a WMI event consumer.
     
    .Description
    Creates a new binding between a WMI event filter and a WMI event consumer.
     
    .Parameter ComputerName
    The computer name to perform the operation against.
     
    .Parameter Namespace
    The WMI namespace to create the instance of __FilterToConsumerBinding in.
     
    .Parameter Filter
    The WMI event filter instance to use for the permanent event filter/consumer binding.
     
    .Parameter Consumer
    The WMI event consumer instance to use for the permanent event filter/consumer binding.
     
    .Parameter SlowDownProviders
    A boolean value that determines whether or not WMI will slow down providers in order to keep up with event processing. NOT RECOMMENDED TO ENABLE!
     
    .Inputs
    No inputs available. Piping objects to New-WmiFilterToConsumerBinding is not possible.
     
    .Outputs
    A System.Management.ManagementObject representing the new __FilterToConsumerBinding WMI instance.
     
    .Link
    http://trevorsullivan.net
     
    .Link
    http://powershell.artofshell.com
#>

function New-WmiFilterToConsumerBinding 
{
    [CmdletBinding(
          SupportsShouldProcess = $false
        , SupportsTransactions  = $false
        , ConfirmImpact         = 'Low'
    )]
    
    #region New-WmiFilterToConsumerBinding Parameters
    param(
        [parameter(
              Mandatory   = $false
            , HelpMessage = "Please specify the computer name to create the binding on."
        )]
        [string]
        ${ComputerName} = 'localhost'
        ,
        [parameter(
              Mandatory   = $false
            , HelpMessage = "Please specify the namespace where you would like to create the filter/consumer binding."
        )]
        [ValidateSet("root\subscription")]
        [string]
        ${Namespace} = 'root\subscription'
        ,
        [parameter(
              Mandatory   = $true
            , HelpMessage = "Please specify the WMI __EventFilter instance to use for this binding."
        )]
        [alias("WmiFilter")]
        [ValidateNotNull()]
        [System.Management.ManagementObject]
        ${Filter}
        ,
        [parameter(
              Mandatory   = $true
            , HelpMessage = "Please specify the WMI event consumer for this binding."
        )]
        [alias("EventConsumer", "WmiEventConsumer")]
        [ValidateNotNull()]
        [System.Management.ManagementObject]
        ${Consumer}
        ,
        [parameter(
              Mandatory   = $false
            , HelpMessage = "Please specify whether or not to maintain security context."
        )]
        [bool]
        ${MaintainSecurityContext} = $false
        ,

        [parameter(
              Mandatory   = $false
            , HelpMessage = "Please specify whether or not to slow down WMI providers in order to keep up with event handling. NOT RECOMMENDED!"
        )]
        [bool]
        ${SlowDownProviders} = $false
    )
    #endregion New-WmiFilterToConsumerBinding Parameters
    
    #region New-WmiFilterToConsumerBinding BEGIN block
    begin
    {
        ${CmdletName} = $Pscmdlet.MyInvocation.MyCommand.Name
        Write-Verbose -Message 'New-WmiFilterToConsumerBinding: Start running BEGIN block'
        # TODO: Validate WMI instance paths passed to ${Filter} and ${Consumer} parameters
        
        # TODO: Validate that the ${Namespace} is valid on the ${ComputerName} specified (test bind)
    }
    #endregion New-WmiFilterToConsumerBinding BEGIN block
    
    #region New-WmiFilterToConsumerBinding PROCESS block
    process
    {
        Write-Verbose -Message "${CmdletName}: Start running PROCESS block"
        
        # Create new in-memory instance of __FilterToConsumerBinding
        ${NewBinding} = ([wmiclass]"\\${ComputerName}\${Namespace}:__FilterToConsumerBinding").CreateInstance()

        # Cannot use braces around the Filter property name, otherwise PowerShell complains. Filter is a keyword in PowerShell
        if (${Filter})
        {
            ${NewBinding}.Filter = ${Filter}.__PATH
            Write-Verbose -Message ("${CmdletName}: Defined the Filter property: " + ${Filter}.__PATH)
        }
        else
        {
            Write-Error -Message 'New-WmiFilterToConsumerBinding: ${Filter} parameter is $null. You must specify a valid instance of __EventFilter to the ${Filter} parameter of this function.'
        }

        # Write-Host ${Consumer}.GetType()
        Write-Debug -Message ("${CmdletName}: Consumer is of type: " + ${Consumer}.GetType())
        # A reference to the __EventConsumer (parent class) of the WMI event consumer
        if (${Consumer})
        {
            ${NewBinding}.{Consumer} = ${Consumer}.__PATH
            Write-Verbose -Message ("${CmdletName}: Defined the Consumer property: " + ${Consumer}.__PATH)
        }
        # If the event consumer is $null, we can't continue with creating the __FilterToConsumerBinding instance
        else
        {
            Write-Error -Message 'New-WmiFilterToConsumerBinding: ${Consumer} is $null. Unable to continue. Please get a reference to a WMI event consumer, or create a new one. Once you have an instance of __EventConsumer, please pass it to this function as the -Consumer parameter.'
        }
        
        ${NewBinding}.{MaintainSecurityContext} = ${MaintainSecurityContext}
        ${NewBinding}.{SlowDownProviders} = ${SlowDownProviders}
        
        ${PutResult} = ${NewBinding}.Put()
        Write-Verbose 'New-WmiFilterToConsumerBinding: Wrote __FilterToConsumerBinding instance to WMI provider.'
    }
    #endregion New-WmiFilterToConsumerBinding PROCESS block
    
    #region New-WmiFilterToConsumerBinding END block
    end
    {
        Write-Verbose -Message 'New-WmiFilterToConsumerBinding: Start running END block'
    }
    #endregion New-WmiFilterToConsumerBinding END block
}

Export-ModuleMember -Function New-WmiFilterToConsumerBinding