Share via

IRTCClientProvisioning2::EnableProfileEx

  • Article

The EnableProfileEx method enables a profile for use in server registration, roaming, and automatic profile selection.

HRESULT EnableProfileEx(IRTCProfile*pProfile,
longlRegisterFlags,
longlRoamingFlags);

Parameters

  • pProfile
    [in] Pointer to a profile to enable on the SIP server.
  • lRegisterFlags
    [in] Integer value containing a set of bit flags that describes registration behaviors. If this value is zero, deregistration will occur. Otherwise, it will be any combination of the RTCRF_* flags.
  • lRoamingFlags
    [in] Integer value containing a set of bit flags that specifies the type of profile to be enabled on the SIP server (such as a buddy or watcher profile). If this value is zero, the profile will be disabled. Otherwise, it will be one of the RTCRMF_* flags.

Return Values

RTC methods may return an RTC_E_ constant.

Value Meaning
RTC_E_CLIENT_NOT_INITIALIZED The client object is not initialized.
RTC_E_UDP_NOT_SUPPORTED The lRoamingFlags parameter is not zero when the registrar specifies UDP as the transport in the profile. Roaming is not supported when the transport is UDP and the lRoamingFlags parameter must be set to zero.
E_INVALIDARG Invalid register flags.
E_POINTER The pProfile parameter is not a valid pointer.

Remarks

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 on the local presence store, see the IRTCClientPresence2::EnablePresenceEx and IRTCClientPresence::EnablePresence methods.

The IRTCClientPresence2::EnablePresenceEx method should be called before registering with the server using the EnableProfileEx method. This method should not be used with the RTC version 1.0 ITRCClientPresence::EnablePresence or ITRCClientProvisioning::EnableProfile method. The RTC Client API version 1.2 restricts the number of enabled profiles to one.

This method extends the functionality of IRTCClientProvisioning::EnableProfile.The profile enabled with this method can be selected for use with IRTCClient::CreateSession and IRTCClientPresence::AddBuddy.

If flag values are specified in lRegisterFlags and the profile contains information about a SIP registrar server, registration will subsequently occur. To deregister a profile, the profile may be disabled with IRTCClientProvisioning::DisableProfile, or reenabled with lRegisterFlags set to zero. The status of registration/deregistration will be communicated as RTCE_REGISTRATION_STATE_CHANGE events.

If flag values are specified in lRoamingFlags, roaming will be started for the profile. To stop roaming, IRTCClientProvisioning::DisableProfile should be called. Roaming status updates will occur as RTCE_ROAMING events. Roaming can only be activated on a method enabled by calling this method.

If a profile is enabled with the same key value as another profile (see the RTC XML schema for information on key values), the existing profile will be disabled and replaced by the newly created profile.

Note   Incoming sessions will not be secure unless the application sets the listen mode to disallow both static and dynamic ports (RTCLM_NONE), and the TLS transport is 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_IRTCClientProvisioning2 is defined as A70909B5-F40E-4587-BB75-E6BC0845023E.

See Also

IRTCClientProvisioning, IRTCClientProvisioning2, IRTCClientProvisioning::EnableProfile, IRTCClientProvisioning::DisableProfile, Presence, Roaming, Security, Buddy Group Events