IRTCClientProvisioning::GetProfile

  • Article

The GetProfile method creates a profile object from the information supplied by this method. Profiles contain information about network resources and accounts that may be used to place calls or handle presence. The profile is obtained asynchronously and an RTCE_PROFILE event is fired when the profile is returned.

Note   This method is supported under the version 1.2 RTC Client API and returns a version 1.2 XML profile.

HRESULT GetProfile(BSTRbstrUserAccount,
BSTRbstrUserPassword,
BSTRbstrUserURI,
BSTRbstrServer,
longlTransport,
LONG_PTRlCookie);

Parameters

  • bstrUserAccount
    [in] BSTR containing the user account information for authenticating the client to the server. This parameter is optional; see the Remarks section for more information.
  • bstrUserPassword
    [in] BSTR containing the user's password for authenticating the client to the server. This parameter is optional; see the Remarks section for more information.
  • bstrUserURI
    [in] BSTR containing the user's URI.
  • bstrServer
    [in] BSTR containing the server information. This parameter is optional; see the Remarks section for more information.
  • lTransport
    [in] The transport type that is used. This parameter is optional; see the Remarks section for more information.
  • lCookie
    [in] The cookie associated with the profile. This parameter is optional; see the Remarks section for more information.

Return Values

RTC methods may return an RTC_E_ constant. The RTC_E_PROFILE_ constants can all be returned from this method.

Value Meaning
E_INVALIDARG Invalid register flags.
RTC_E_CLIENT_NOT_INITIALIZED The client is not initialized.
RTC_E_NO_TRANSPORT No transport was specified in the lTransport parameter. If the bstrServer parameter is specified, the lTransport parameter must also be specified.
RTC_E_UDP_NOT_SUPPORTED The application attempted to specify an authentication method not supported under the UDP transport. If any server listed in the profile specifies the UDP transport, Digest is the only authentication method allowed. All other authentication methods will be rejected.

Remarks

The TLS transport is required when Basic is specified as the authentication method in the profile. The Kerberos and NTLM authentication methods are supported over the TCP or TLS transport methods. If the UDP transport is specified for any server listed in the profile, and Basic, Kerberos, USE_LOGON_CRED, or NTLM is requested, the profile will be rejected.

The profile created by this method is returned asynchronously from the server. The application receives an event of type RTCE_PROFILE to indicate the profile has been returned. The IRTCEventNotification::Event method returns the IRTCProfileEvent interface in the pEvent parameter. The IRTCProfileEvent::get_Profile method contains the profile in the ppProfile parameter and the IRTCProfileEvent2::get_EventType method returns the event type RTCPFET_PROFILE_GET. The application should retrieve the profile from the get_Profile method before performing the operations specific to the profile.

Except for the bstrUserURI parameter, the parameters supplied in this method are optional.

If the bstrServer parameter is specified, the lTransport parameter must also be specified. If the bstrServer parameter is not specified, the RTC Client API attempts to locate a server by performing a DNS lookup for the domain specified in the User URI. The RTC Client API uses the following logic to locate a SIP server, given the domain portion of the users SIP URI:

  1. Attempt to find an SRV record for the domain using the transport specified in the lTransport parameter. If no transport is specified in the lTransport parameter, attempt an SRV lookup using each of the following in the specified order until an SRV record is found:

    • TLS
    • TCP
    • UDP

    If an SRV record is found, the RTC API places this server in the profile. If no SRV record is found, continue with the next step.

  2. Attempt to find an A record for the SIP.Domain. For example, if the URI is someone@example.com, the RTC API will try sip.example.com. If an A record is found, attempt to connect to the server using the IP address with the transport specified in the lTransport parameter. If no transport is specified try to connect using TLS. If this fails, then the server cannot be found.

If the lTransport parameter is not supplied (lTransport=0), the Client API performs a DNS lookup in the domain supplied by the User URI. The RTC API attempts to locate a TLS entry first, then if this fails, the RTC API attempts to obtain an SRV record for TCP, and if this fails, the RTC API attempts to locate a UDP entry. Once a server is found, the DNS search process is stopped. If multiple entries are returned for a specified transport type, the RTC Client API stores only one server entry.

The lCookie parameter is used by the application to track multiple calls to the GetProfile method. If the application plans to call this method only once, this parameter can be set to zero or left blank.

The location of the SIP server is found through a strict lookup of the DNS name unless the client object was initialized with the RTCIF_DISABLE_STRICT_DNS flag. This flag disables the strict naming conventions followed by the DNS search request engine. For example, if the application called the IRTCClient2::InitializeEx method without enabling RTCIF_DISABLE_STRICT_DNS, and the bstrServer parameter of the GetProfile method is not specified, and the bstrUserURI parameter specifies SIP:USER1@EXAMPLE.COM, the DNS SRV record must be either Example.Com or SIP.Example.Com. In other words, the fully qualified domain name (FQDN) of the server must exactly match the domain portion of the user's SIP URI, or the FQDN must be SIP followed by the domain portion of the user's SIP URI. This prevents man-in-the-middle security violations, where an attacker can potentially intercept the UDP messages that the client uses to perform the DNS lookup, and respond to the client with the name of an unauthorized SIP server. The attacker could then impersonate a trusted user, or the server could cause the client to authenticate using weak encryption.

If the application called IRTCClient2::InitializeEx with the RTCIF_DISABLE_STRICT_DNS flag specified, the DNS SRV record lookup is less specific. For example, the SIP:User1@Example.Com in the previous example can now match to SIP.Division.Example.Com or RTC.Example.Com. However, an attacker can also respond to the DNS query with a response that contains Attacker.Example.Com.

Note  It is possible for someone to intercept information by replacing the SIP server, which would result in forwarding SIP requests to erroneous servers. The application should therefore ensure that a means to authenticate the server is enabled. For the application to authenticate the server, the Kerberos authentication method should be enabled and the TLS transport type must be specified in the profile.

Requirements

Redistributable: Requires Rtcdll.dll on Windows 2000, Windows XP, and Windows Server 2003.
Header: Declared in Rtccore.h.
Library: Included as a resource in Rtcdll.dll.
GUID: IID_IRTCClientProvisioning is defined as B9F5CF06-65B9-4a80-A0E6-73CAE3EF3822.

See Also

IRTCClientProvisioning, IRTCProfile, Create and Enable a Profile, IRTCClientProvisioning::CreateProfile, IRTCClientProvisioning::DisableProfile, Presence, Roaming, Security, Create the Roaming Profile