Share via

Add Method of the IFPCUserAgentMappings Interface

  • Article

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

C++

Syntax

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

Parameters

  • UserAgent
    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.

  • FormsType
    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
    Address of an interface pointer that on return points to the new IFPCUserAgentMapping interface created.

Return Value

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.

Visual Basic

Syntax

Function Add( _
  ByVal UserAgent As String, _
  ByVal FormsType As FpcFBAFormsTypes _
) As FPCUserAgentMapping

Parameters

  • UserAgent
    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
    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.

Return Value

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.

Example Code

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

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.

Requirements

Client Requires Windows 7 or Windows Vista.
Server Requires Windows Server 2008 R2 or Windows Server 2008 x64 Edition with SP2.
Version Requires Forefront Threat Management Gateway (TMG) 2010.
IDL

Declared in Msfpccom.idl.
DLL

Requires Msfpccom.dll.

See Also

FPCUserAgentMappings

Send comments about this topic to Microsoft

Build date: 6/30/2010