IFPCUserAgentMappings::Add method

Article
08/27/2012

Applies to: desktop apps only

The Add method creates a new FPCUserAgentMapping object in the collection and returns a reference to it.

Syntax

HRESULT Add(
  [in]   BSTR UserAgent,
  [in]   FpcFBAFormsTypes FormsType,
  [out]  IFPCUserAgentMapping **ppUserAgentMapping
);

FPCUserAgentMappings.Add( _
  ByVal UserAgent As String, _
  ByVal FormsType As FpcFBAFormsTypes, _
  ByRef ppUserAgentMapping As IFPCUserAgentMapping _
) As FPCUserAgentMapping

Parameters

UserAgent [in]

C++	Required. BSTR that specifies the User-Agent headers to which the mapping will apply. The string may contain wildcard characters (). A string containing only a wildcard character () applies to all User-Agent headers. A string that begins and ends with a wildcard character applies to any User-Agent header that contains the substring between the wildcard characters.
VB	Required. String that specifies the User-Agent headers to which the mapping will apply. The string may contain wildcard characters (). A string containing only a wildcard character () applies to all User-Agent headers. A string that begins and ends with a wildcard character applies to any User-Agent header that contains the substring between the wildcard characters.

FormsType [in]
Required. Value from the FpcFBAFormsTypes enumerated type that specifies the type of authentication that will be associated with the User-Agent headers specified in the mapping. The possible values specify forms-based authentication using forms written in a specific format or Basic authentication.
ppUserAgentMapping [out]
Address of an interface pointer that on return points to the new IFPCUserAgentMapping interface created.

Return value

C++

This method can return one of the following:

S_OK, indicating that the operation succeeded.
An error code, indicating that the operation failed. In this case, the [out] parameter returned is a null object.

VB

This method returns a reference to an FPCUserAgentMapping object if successful. Otherwise, an error is raised that can be intercepted by using an error handler.

Remarks

The new User-Agent mapping created is added to the list of User-Agent mappings in the position preceding the last User-Agent mapping. Its ordinal position the list of User-Agent mappings, which is specified by the Order property, can be modified by calling the MoveUp and MoveDown methods.

Examples

This VBScript script creates a new User-Agent mapping that maps User-Agent headers to a type of authentication, which can be forms-based authentication using forms written in a specific format or Basic authentication.

Option Explicit
 
' Define the constants needed.
Const Error_AlreadyExists = &H800700B7
Const fpcFbaHTML4 = 0
Const fpcFbaCHTML = 1
Const fpcFbaXHTML_MP = 2
Const fpcFbaHTTPBASIC = 3
 
Main(WScript.Arguments)
 
Sub Main(args)
    If(args.Count <> 2) Then
        Usage()
    Else
        Select Case UCase(args(1))
            Case "HTML4" 
                AddUAMapping args(0), fpcFbaHTML4 
            Case "CHTML" 
                AddUAMapping args(0), fpcFbaCHTML
            Case "XHTML" 
                AddUAMapping args(0), fpcFbaXHTML_MP
            Case "BASIC" 
                AddUAMapping args(0), fpcFbaHTTPBASIC
            Case Else
                WScript.Echo "The AuthType parameter specified is not valid."
                Usage()
        End Select
    End If
End Sub
 
Sub AddUAMapping(uaHeaders, authType)
 
    ' Create the root object.
    Dim root  ' The FPCLib.FPC root object
    Set root = CreateObject("FPC.Root")
 
    ' Declare the other objects needed.
    Dim isaArray    ' An FPCArray object
    Dim mappings    ' An FPCUserAgentMappings collection
    Dim newMapping  ' An FPCUserAgentMapping object
    ' Get references to the array object and
    ' the User-Agent mappings collection.
    Set isaArray = root.GetContainingArray()
    Set mappings = isaArray.RuleElements.UserAgentMappings
 
    ' Create a new User-Agent mapping.
    On Error Resume Next
    Set newMapping = mappings.Add(uaHeaders, authType)
    If Err.Number = Error_AlreadyExists Then
       WScript.Echo "A mapping for the User-Agent headers specified already exists."
       WScript.Quit
    End If
    On Error GoTo 0
 
    ' Save the changes to the collection of User-Agent mappings.
    mappings.Save
    WScript.Echo "Done!"
End Sub
 
Sub Usage()
    WScript.Echo "Usage:" & VbCrLf _
        & "  " & WScript.ScriptName & " UAHeaders AuthType" & VbCrLf _
        & "" & VbCrLf _
        & "  UAHeaders   String that specifies User-Agent headers." & VbCrLf _ 
        & "  AuthType    HTML4   FBA with HTML 4.01 forms" & VbCrLf _
        & "              CHTML   FBA with cHTML forms" & VbCrLf _
        & "              XHTML   FBA with XHTML-MP forms" & VbCrLf _
        & "              Basic   Basic authentication"
    WScript.Quit
End Sub

Requirements

Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 (64-bit only)
Version	Forefront Threat Management Gateway (TMG) 2010
IDL	Msfpccom.idl
DLL	Msfpccom.dll