# *****************************************************************************
# Best Practices Library For PowerShell
# *****************************************************************************
#
# (c) Quest Software Corporation, Moscow Office
#
# last modified: 2012/03/29
#===========================================================================
# IsObjectClassRequested
#===========================================================================
# This function determines if the request was issued for the specified
# object class. It can be useful to force the script policy event handler
# to be triggered for the specified object class only.
#
# Parameters
# $ClassName - string with object class name. It can be in any cases,
# for example "User", "GROUP", "computer"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# $true - When operation target object type equals to $ClassName
# $false - When operation target object type does not equal to $ClassName
# Remarks
# This function is applicable to any event handlers
#
function IsObjectClassRequested([string]$ClassName, $Request)
{
return ($Request.Class -ieq $ClassName)
} #-- IsObjectClassRequested
#===========================================================================
# AreObjectClassesRequested
#===========================================================================
# This function determines if the request was issued for any of the
# specified object classes. It can be useful to force the script policy event
# handlerto be triggered for the specified object classes only.
#
# Parameters
# $ClassNames - string array with object class names. Names can be in any
# cases for example "User", "GROUP", "computer"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# $true - When operation target object type equals to any of $ClassNames
# $false - When operation target object type does not equal to any of $ClassNames
# Remarks
# This function is applicable to any event handlers
#
function AreObjectClassesRequested([array]$ClassNames, $Request)
{
return (($ClassNames | %{ IsObjectClassRequested $_ $Request }) -contains $true)
} #-- AreObjectClassesRequested
#===========================================================================
# IsAttributeModified
#===========================================================================
# This function determines if modification for the specified attribute
# is requested. It can be useful to force the script policy event handler
# to be triggered for the specified attribute modification only.
#
# Parameters
# $AttributeName - string with attribute name. It can be in any cases,
# for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# $true - When specified by $AttributeName attribute is modified during
# request
# $false - When specified by $AttributeName attribute is not modified
# during request
# Remarks
# This function is applicable to onPreCreate, onPostCreate, onPreModify,
# onPostModify, and onCheckPropertyValues event handlers.
#
function IsAttributeModified ([string]$AttributeName, $Request)
{
$objEntry = $Request.GetPropertyItem($AttributeName, $Constants.ADSTYPE_CASE_IGNORE_STRING)
if ($objEntry -eq $null) { return $false }
if ($objEntry.ControlCode -eq 0) { return $false }
return $true
} #-- IsAttributeModified
#===========================================================================
# AreAttributesModified
#===========================================================================
# This function determines if modification for any of the specified
# attributes is requested. It can be useful to force the script policy event
# handler to be triggered for the specified attributes modification only.
#
# Parameters
# $AttributeNames - string array with attribute names. Names can be in any
# cases,for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# $true - When any of specified by $AttributeNames attributes is modified
# during request
# $false - When any of specified by $AttributeNames attributes is not
# modified during request
# Remarks
# This function is applicable to onPreCreate, onPostCreate, onPreModify,
# onPostModify, and onCheckPropertyValues event handlers.
#
function AreAttributesModified ([array]$AttributeNames, $Request)
{
return (($AttributeNames | %{ IsAttributeModified $_ $Request }) -contains $true)
} #-- AreAttributesModified
#===========================================================================
# RemoveModifiedAttribute
#===========================================================================
# This function determines if modification for the specified attribute
# is requested. It can be useful to force the script policy event handler
# to be triggered for the specified attribute modification only.
#
# Parameters
# $AttributeName - string with attribute name. It can be in any cases,
# for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# No return values
# Remarks
# This function is applicable to onPreCreate, onPostCreate, onPreModify,
# onPostModify, and onCheckPropertyValues event handlers.
#
function RemoveModifiedAttribute ([string]$AttributeName, $Request)
{
$Request.ResetPropertyItem($AttributeName)
} #-- RemoveModifiedAttribute
#===========================================================================
# IsAttributeRequested
#===========================================================================
# This function determines if the specified attribute is requested
# to read.
#
# Parameters
# $AttributeName - string with attribute name. It can be in any cases,
# for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# $true - When specified by $AttributeName attribute is requested during
# request
# $false - When specified by $AttributeName attribute is not requested
# during request
# Remarks
# This function is applicable to onPreget, onPostGet, onPreSearch
# event handlers.
#
function IsAttributeRequested ([string]$AttributeName, $Request)
{
return $Request.IsAttributeRequested($AttributeName)
} #-- IsAttributeRequested
#===========================================================================
# AreAttributesRequested
#===========================================================================
# This function determines if any of the specified attributes is requested
# to read.
#
# Parameters
# $AttributeNames - string array with attribute names. Names can be in any
# cases, for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# $true - When any of specified by $AttributeNames attributes is requested
# during request
# $false - When any of specified by $AttributeNames attributes is not
# requested during request
# Remarks
# This function is applicable to onPreget, onPostGet, onPreSearch
# event handlers.
#
function AreAttributesRequested ([array]$AttributeNames, $Request)
{
return (($AttributeNames | %{ IsAttributeRequested $_ $Request }) -contains $true)
} #-- AreAttributesRequested
#===========================================================================
# AddRequestedAttribute
#===========================================================================
# This function adds the specified attribute to the list of requested
# attributes to read.
#
# Parameters
# $AttributeName - string with attribute name. It can be in any cases,
# for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# No return values
# Remarks
# This function is applicable to onPreget, onPostGet, onPreSearch
# event handlers.
#
function AddRequestedAttribute ([string]$AttributeName, $Request)
{
$Request.AddRequestedAttribute($AttributeName)
} #-- AddRequestedAttribute
#===========================================================================
# IsAttributeGenerationRequested
#===========================================================================
# This function determines if a server-side generation for the specified
# attribute is requested.
#
# Parameters
# $AttributeName - string with attribute name. It can be in any cases,
# for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# $true - When a server-side generation for specified by $AttributeName
# attribute is requested
# $false - When a server-side generation for specified by $AttributeName
# attribute is not requested
# Remarks
# This function is applicable to onGetEffectivePolicy event handler only.
#
function IsAttributeGenerationRequested ([string]$AttributeName, $Request)
{
$requestedAttributes = GetInControl $Constants.EDS_CONTROL_FULL_EFFECTIVE_POLICY_INFO $Request
if ($requestedAttributes -eq $null) { return $false }
return ($requestedAttributes -icontains $AttributeName)
} #-- IsAttributeGenerationRequested
#===========================================================================
# GetAttribute
#===========================================================================
# This function returns a value of the specified attribute of
# the specified object. It can be useful to prevent an error
# rising when the attribute has no value.
#
# Parameters
# $AttributeName - string with attribute name. It can be in
# any cases, for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $ADSIObject - the Request object, or the DirObj object, or any other
# ADSI-compatible COM-object. Please see ARS SDK for details
# Return value
# Integer, string, boolean value, or array of values - When specified by
# $AttributeName attribute has any values
# Empty value - specified by $AttributeName attribute has no value
# Remarks
# This function is applicable to onPreGet, onPostGet, onPreCreate,
# onPostCreate, onPreModify, onPostModify, and onCheckPropertyValues
# event handlers.
#
function GetAttribute ([string]$AttributeName, $ADSIObject)
{
trap { continue }
return $ADSIObject.Get($AttributeName)
} #-- GetAttribute
#===========================================================================
# GetMultiValuedAttribute
#===========================================================================
# This function returns an array of values of the specified attribute of
# the specified object. It can be useful to prevent an error rising when
# the attribute has no value.
#
# Parameters
# $AttributeName - string with attribute name. It can be in any cases,
# for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $ADSIObject - the Request object, or the DirObj object, or any other
# ADSI-compatible COM-object. Please see ARS SDK for details
# Return value
# Array of integer, string, or boolean values - When specified by
# $AttributeName attribute has any values
# Empty value - When specified by $AttributeName attribute has no value
# Remarks
# This function is applicable to onPreGet, onPostGet, onPreCreate,
# onPostCreate, onPreModify, onPostModify, and onCheckPropertyValues
# event handlers.
#
function GetMultiValuedAttribute ([string]$AttributeName, $ADSIObject)
{
trap { continue }
return $ADSIObject.GetEx($AttributeName)
} #-- GetMultiValuedAttribute
#===========================================================================
# GetActualAttribute
#===========================================================================
# This function returns an array of values of the specified attribute of
# the specified object. It can be useful to prevent an error rising when
# the attribute has no value.
#
# Parameters
# $AttributeName - string with attribute name. It can be in any cases,
# for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $ADSIObject - the Request object, or the DirObj object, or any other
# ADSI-compatible COM-object. Please see ARS SDK for details
# Return value
# Array of integer, string, or boolean values - When specified by
# $AttributeName attribute has any values
# Empty value - When specified by $AttributeName attribute has no value
# Remarks
# This function is applicable to onPreGet, onPostGet, onPreCreate,
# onPostCreate, onPreModify, onPostModify, and onCheckPropertyValues
# event handlers.
#
function GetActualAttribute ([string]$AttributeName, $ADSIObject)
{
if (IsAttributeModified $AttributeName $ADSIObject)
{
return (GetAttribute $AttributeName $ADSIObject)
}
else
{
trap { continue }
[void]$DirObj.GetInfoEx(@($AttributeName),0)
return (GetAttribute $AttributeName $DirObj)
}
} #-- GetActualAttribute
#===========================================================================
# PutAttribute
#===========================================================================
# This function returns a value of the specified attribute of
# the specified object. It can be useful to prevent an error
# rising when the attribute has no value.
#
# Parameters
# $AttributeName - string with attribute name. It can be in
# any cases, for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $ADSIObject - the Request object, or the DirObj object, or any other
# ADSI-compatible COM-object. Please see ARS SDK for details
# Return value
# Integer, string, boolean value, or array of values - When specified by
# $AttributeName attribute has any values
# Empty value - specified by $AttributeName attribute has no value
# Remarks
# This function is applicable to onPreGet, onPostGet, onPreCreate,
# onPostCreate, onPreModify, onPostModify, and onCheckPropertyValues
# event handlers.
#
function PutAttribute ([string]$AttributeName, $Value, $ADSIObject)
{
if (($Value -eq $null) -or ($Value -eq ''))
{
[void]$ADSIObject.PutEx($Constants.ADS_PROPERTY_CLEAR, $AttributeName, $null)
}
else
{
[void]$ADSIObject.Put($AttributeName, $Value)
}
} #-- PutAttribute
#===========================================================================
# GetRequestParameter
#===========================================================================
# This function returns a value of the specified parameter of
# the Request object. It can be useful to prevent an error
# rising when the attribute has no value.
#
# Parameters
# $ParameterName - string with parameter name. It can be in
# any cases, for example "MyParameter", "MYPARAMETER"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# Integer, string, boolean value, or array of values - When specified by
# $ParameterName parameter has any values
# Empty value - specified by $ParameterName parameter has no value
# Remarks
# This function is applicable to onPreGet, onPostGet, onPreCreate,
# onPostCreate, onPreModify, onPostModify, and onCheckPropertyValues
# event handlers.
#
function GetRequestParameter ([string]$ParameterName, $Request)
{
trap { continue }
return $Request.Parameter[$ParamaterName]
} #-- GetRequestParameter
#===========================================================================
# GetInControl
#===========================================================================
# This function returns a value of the specified ARS input control of
# the Request object. It can be useful to prevent an error rising when the
# input control has no value.
#
# Parameters
# $ControlName - string with ARS input control name. It can be in any
# cases, for example "myControl", "MYCONTROL"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# Integer, string, boolean value, or array of values - When specified by
# $ControlName ARS input control has any values
# Empty value - When specified by $ControlName ARS input control has no
# value
# Remarks
# This function is applicable to onPreGet, onPostGet, onPreCreate,
# onPostCreate, onPreModify, onPostModify, and onCheckPropertyValues
# event handlers.
#
function GetInControl ([string]$ControlName, $Request)
{
trap { continue }
return $Request.GetInControl($ControlName)
} #-- GetInControl
#===========================================================================
# GetOutControl
#===========================================================================
# This function returns a value of the specified ARS output control of
# the Request object. It can be useful to prevent an error rising when the
# output control has no value.
#
# Parameters
# $ControlName - string with ARS input control name. It can be in any
# cases, for example "myControl", "MYCONTROL"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# Integer, string, boolean value, or array of values - When specified by
# $ControlName ARS input control has any values
# Empty value - When specified by $ControlName ARS output control has no
# value
# Remarks
# This function is applicable to onPreGet, onPostGet, onPreCreate,
# onPostCreate, onPreModify, onPostModify, and onCheckPropertyValues
# event handlers.
#
function GetOutControl ([string]$ControlName, $Request)
{
trap { continue }
return $Request.GetOutControl($ControlName)
} #-- GetOutControl
#===========================================================================
# PutInControl
#===========================================================================
# This function sets a value of the specified ARS input control of
# the Request object.
#
# Parameters
# $ControlName - string with ARS input control name. It can be in any
# cases, for example "myControl", "MYCONTROL"
# $Value - any type value to set to the input control
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# No return values
# Remarks
# This function is applicable to onPreGet, onPostGet, onPreCreate,
# onPostCreate, onPreModify, onPostModify, and onCheckPropertyValues
# event handlers.
#
function PutInControl ([string]$ControlName, $Value, $Request)
{
[void]$Request.PutInControl($ControlName, $Constants.ADSTYPE_CASE_IGNORE_STRING, $Value)
} #-- PutInControl
#===========================================================================
# PutOutControl
#===========================================================================
# This function sets a value of the specified ARS output control of
# the Request object.
#
# Parameters
# $ControlName - string with ARS input control name. It can be in any
# cases, for example "myControl", "MYCONTROL"
# $Value - any type value to set to the output control
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# No return values
# Remarks
# This function is applicable to onPreGet, onPostGet, onPreCreate,
# onPostCreate, onPreModify, onPostModify, and onCheckPropertyValues
# event handlers.
#
function PutOutControl ([string]$ControlName, $Value, $Request)
{
[void]$Request.PutOutControl($ControlName, $Constants.ADSTYPE_CASE_IGNORE_STRING, $Value)
} #-- PutOutControl
#===========================================================================
# ReportValidationError
#===========================================================================
# This function report an error message on invalid value of attribute
#
# Parameters
# $AttributeName - string with attribute name. It can be in
# any cases, for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $ErrorMessage - string with error message
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# No return values
# Remarks
# This function is applicable to onPreCreate, onPostCreate, onPreModify,
# onPostModify, and onCheckPropertyValues event handlers.
#
function ReportValidationError ([string]$AttributeName, [string]$ErrorMessage, $Request)
{
$requestType = $Request.Parameter('Type')
if ($requestType -eq $Constants.EDST_REQ_CHECK_PROPERTY_VALUES)
{
$Request.SetPolicyComplianceInfo($AttributeName, $Constants.EDS_POLICY_COMPLIANCE_ERROR, $ErrorMessage)
}
else
{
throw ($ErrorMessage + "Attribute: $AttributeName")
}
} #-- ReportValidationError
#===========================================================================
# ExecutePolicyRule
#===========================================================================
# This function generates a value in accordance with a PVG generation rule
#
# Parameters
# $PolicyRule - string with PVG geneartion rule
# $Request - the Request object. Please see ARS SDK for details about this
# object
# Return value
# String with generated value
# Remarks
# This function is applicable to onPreCreate, onPostCreate, onPreModify,
# onPostModify, and onCheckPropertyValues event handlers.
#
function ExecutePolicyRule ([string]$PolicyRule , $Request)
{
$value = $PolicyRule
$rex = [regex]'(?:%<(?<name>.+?)>)'
$neededAttributes = $rex.Matches($PolicyRule) | %{ $_.Groups['name'].Value }
$neededAttributes | %{ $value = $value -replace ('%<' + $_ + '>'),(GetActualAttribute $_ $Request) }
return $value
} #-- ExecuteGenerationRule
#===========================================================================
# ValidateAndGenerateAttribute
#===========================================================================
# This function validates attribute value and additionally generates value
# for attribute
#
# Parameters
# $AttributeName - string with attribute name. It can be in
# any cases, for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# $IsValueRequired - boolean value indicating if attribute must have a value
# $PossibleValues - array with possible values
# $PolicyRule - string with PVG geneartion rule
# $GeneratedValue- default value for attribute specified by $AttributeName
# $IsRestricted - boolean value indicating possible values are forced
# $IsAutoGenerated - boolean value indicating if the default value is forced
# Return value
# No return values
# Remarks
# This function is applicable to onPreCreate, onPostCreate, onPreModify,
# onPostModify, and onCheckPropertyValues event handlers.
#
function ValidateAndGenerateAttribute ([string]$AttributeName, $Request, [bool]$IsValueRequired, [array]$PossibleValues, [string]$PolicyRule, $GeneratedValue, [bool]$IsRestricted, [bool]$IsAutoGenerated, [string]$DisplayNote = 'Attribute valued does not conform to corporate policy')
{
$value = GetActualAttribute $AttributeName $Request
if ($PSBoundParameters.ContainsKey('IsValueRequired'))
{
if (! $value)
{
ReportValidationError $AttributeName $DisplayNote $Request
return
}
}
if ($PSBoundParameters.ContainsKey('PossibleValues'))
{
if ($PossibleValues -inotcontains $value)
{
ReportValidationError $AttributeName $DisplayNote $Request
return
}
}
if ($PSBoundParameters.ContainsKey('PolicyRule'))
{
$generatedValue = ExecutePolicyRule $PolicyRule $Request
if ($value -ne $generatedValue)
{
ReportValidationError $AttributeName $DisplayNote $Request
return
}
}
} #-- ValidateAndGenerateAttribute
#===========================================================================
# SetEffectivePolicy
#===========================================================================
# This function prepares effectice policies for attribute
#
# Parameters
# $AttributeName - string with attribute name. It can be in
# any cases, for example "edsvaMyAttribute", "EDSVAMYATTRIBUTE"
# $Request - the Request object. Please see ARS SDK for details about this
# object
# $IsValueRequired - boolean value indicating if attribute must have a value
# $PossibleValues - array with possible values
# $PolicyRule - string with PVG geneartion rule
# $GeneratedValue- default value for attribute specified by $AttributeName
# $IsRestricted - boolean value indicating possible values are forced
# $IsAutoGenerated - boolean value indicating if the default value is forced
# $DisplayNote - string with display note
# $IsServerSideGenerated - boolean value indicating that attribute will be
# generated on server side
# Return value
# No return values
# Remarks
# This function is applicable to onGetEffectivePolicy event handler only
#
function SetEffectivePolicy ([string]$AttributeName, $Request, [bool]$IsValueRequired, [array]$PossibleValues, [string]$PolicyRule, $GeneratedValue, [bool]$IsRestricted, [bool]$IsAutoGenerated, [string]$DisplayNote, [bool]$IsServerSideGenerated)
{
if ($PSBoundParameters.ContainsKey('IsValueRequired'))
{
if ($IsValueRequired)
{
[void]$Request.SetEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_VALUE_REQURIED, 'any')
}
else
{
[void]$Request.ClearEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_VALUE_REQURIED)
}
}
if ($PSBoundParameters.ContainsKey('PossibleValues'))
{
[void]$Request.SetEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_POSSIBLE_VALUES, $PossibleValues)
}
if ($PSBoundParameters.ContainsKey('PolicyRule'))
{
[void]$Request.SetEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_POLICY_RULE, $PolicyRule)
}
if ($PSBoundParameters.ContainsKey('GeneratedValue'))
{
[void]$Request.SetEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_GENERATED_VALUE, $GeneratedValue)
}
if ($PSBoundParameters.ContainsKey('IsRestricted'))
{
if ($IsRestricted)
{
[void]$Request.SetEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_RESTRICTED, 'any')
}
else
{
[void]$Request.ClearEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_RESTRICTED)
}
}
if ($PSBoundParameters.ContainsKey('IsAutoGenerated'))
{
if ($IsAutoGenerated)
{
[void]$Request.SetEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_AUTO_GENERATED, 'any')
}
else
{
[void]$Request.ClearEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_AUTO_GENERATED)
}
}
if ($PSBoundParameters.ContainsKey('DisplayNote'))
{
[void]$Request.SetEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_DISPLAY_NOTE, $DisplayNote)
}
if ($PSBoundParameters.ContainsKey('IsServerSideGenerated'))
{
if ($IsServerSideGenerated)
{
[void]$Request.SetEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_SERVER_SIDE_GENERATED, 'any')
}
else
{
[void]$Request.ClearEffectivePolicyInfo($AttributeName, $Constants.EDS_EPI_UI_SERVER_SIDE_GENERATED)
}
}
} #-- SetEffectivePolicy
# ****** END OF CODE **********************************************************