# *****************************************************************************
#                  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 **********************************************************