IRTCClientProvisioning::GetProfile (Windows Embedded CE 6.0)

1/6/2010

This method creates a Profile object from the information supplied.

Profiles contain information about network resources and accounts that can be used to place calls or handle presence.

The profile is obtained asynchronously and the method fires an RTCE_PROFILE event when the profile is retrieved.

Note

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

Syntax

HRESULT GetProfile(
  BSTR bstrUserAccount,
  BSTR bstrUserPassword,
  BSTR bstrUserURI,
  BSTR bstrServer,
  long lTransport,
  LONG_PTR lCookie
);

Parameters

• bstrUserAccount
  [in] Optional. User account information for authenticating the client to the server.

  If the application does not supply this parameter, the RTC Client API uses the NT credentials.

• bstrUserPassword
  [in] Optional. User's password for authenticating the client to the server.

  If the application does not supply this parameter, the RTC Client API uses the NT credentials.

• bstrUserURI
  [in] The user's URI.

• bstrServer
  [in] Optional. Server information.

  If this parameter is not supplied, the RTC Client API attempts to locate a server by performing a DNS lookup for the domain specified in the user URI.

• lTransport
  [in] Optional. Transport type.

  If this parameter is not supplied, the RTC Client API performs a DNS lookup in the domain supplied by the User URI. For more details, see the Remarks section.

• lCookie
  [in] Optional. The cookie associated with the profile.

  If supplied, the application uses it to track multiple calls to GetProfile.

  If the application plans to call this method only once, it can set this parameter 0 or leave it blank.

Return Value

This method can return an RTC_E_ constant.

The following table shows additional return values..

Value	Meaning
E_INVALIDARG	Invalid register flags.
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 a server listed in the profile specifies the UDP transport, Digest is the only authentication method allowed. All other authentication methods are rejected.

Remarks

The TLS transport is required when Basic authentication is specified 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 a server listed in the profile and Basic, Kerberos, USE_LOGON_CRED, or NTLM is requested, the profile is 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::Profile method contains the profile in the ppProfile parameter and the IRTCProfileEvent2::EventType method returns the event type RTCPFET_PROFILE_GET.

The application should retrieve the profile from the IRTCProfileEvent::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 bstrUserURI parameter.

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 Client 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 Client API tries 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 RTC Client API performs a DNS lookup in the domain supplied by the User URI.

The RTC Client API attempts to locate a TLS entry first. If this fails, it attempts to obtain an SRV record for TCP. If this too fails, the RTC Client API attempts to locate a UDP entry.

When 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 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, suppose the application calls the IRTCClient2::InitializeEx method without enabling RTCIF_DISABLE_STRICT_DNS, without specifying server information using the bstrServer parameter of the GetProfile method, and by setting the bstrUserURI parameter to sip:user1@example.com. In this case, 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 calls 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.

Security 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

Header	rtccore.h, rtccore.idl
Library	uuid.lib
Windows Embedded CE	Windows CE .NET 4.0 and later

See Also

Reference

IRTCClientProvisioning
IRTCClient2::InitializeEx
IRTCClientProvisioning::EnumerateProfiles
IRTCEventNotification::Event
IRTCProfile
IRTCProfileEvent
IRTCProfileEvent::Profile
IRTCProfileEvent2::EventType