IRTCClientProvisioning2::EnableProfileEx (Windows Embedded CE 6.0)

1/6/2010

This method enables a profile for use in server registration, roaming, and automatic profile selection. It extends the functionality of IRTCClientProvisioning::EnableProfile.

Before the application calls this method, it must call IRTCClientPresence2::EnablePresenceEx.

Note

The version 1.2 RTC Client API restricts the number of enabled profiles to one.

Syntax

HRESULT EnableProfileEx( 
  IRTCProfile* pProfile, 
  long lRegisterFlags, 
  long lRoamingFlags 
);

Parameters

• pProfile
  [in] Pointer to the IRTCProfile interface for the profile to enable on the SIP server.

• lRegisterFlags
  [in] RTCRF_ constants describing registration behaviors.

  If this value is zero, deregistration occurs.

• lRoamingFlags
  [in] RTCRMF_ constants specifying roaming behaviors.

  If this value is zero, the profile will be disabled for roaming.

Return Value

This method can return an RTC_E_ constant.

The following table shows additional possible return values.

Value	Meaning
E_INVALIDARG	Invalid register flags.
E_POINTER	The pProfile parameter is not a valid pointer.

Remarks

The profiles enabled with this method can be selected for use by IRTCClient::CreateSession and IRTCClientPresence::AddBuddy.

If lRegisterFlags specifies flags, and the profile contains information about a SIP registrar server, registration occurs.

To trigger deregistration, the profile can be disabled with IRTCClientProvisioning::DisableProfile or enabled again with the lRegisterFlags parameter set to zero.

The status of registration and deregistration is notified with RTCE_REGISTRATION_STATE_CHANGE events.

If the application specifies flags in the lRoamingFlags parameter, roaming is started for the profile.

Roaming status updates occurs as RTCE_ROAMING events.

To stop roaming, the application should call DisableProfile. Roaming can only be activated on a profile enabled by calling this method.

Roaming contacts (specified in the RTCRMF_* flags) are not supported when the registrar server in the profile specifies the UDP transport; the lRoamingFlags parameter must be set to zero.

If UDP is the transport, local contacts and group are supported and can be added to the local presence store. For more information about the local presence store, see the IRTCClientPresence2::EnablePresenceEx and IRTCClientPresence::EnablePresence methods.

If a profile is enabled with the same key value as an existing enabled profile, the existing profile will be disabled and replaced by the new profile. For information about provisioning, see the RTC Client API XML Schema.

Security Note:

This method can send data over the network in unencrypted form. Therefore, someone eavesdropping on the network could read the data. Before using this method in an unencrypted session, consider the security risk of sending the data in clear text. An RTC session can be encrypted by specifying TLS in the profile used for the session. In addition, the application can set the listen mode to disallow both static and dynamic ports, using the RTCLM_NONE enumeration value. For information, see RTC_LISTEN_MODE.

Requirements

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

See Also

Reference

IRTCClientProvisioning2
RTC Client API XML Schema
IRTCClient::CreateSession
IRTCClientPresence::AddBuddy
IRTCClientPresence::EnablePresence
IRTCClientProvisioning::DisableProfile
IRTCClientProvisioning::EnableProfile
IRTCClientProvisioning::EnumerateProfiles
IRTCClientProvisioning::Profiles
IRTCProfile