IUccSession.CreateParticipant Method

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Creates a new instance of IUccSessionParticipant for a remote participant.

Namespace: Microsoft.Office.Interop.UccApi
Assembly: Microsoft.Office.Interop.UccApi (in microsoft.office.interop.uccapi.dll)

Syntax

'Declaration
Function CreateParticipant ( _
    pUri As UccUri, _
    pContext As UccContext _
) As IUccSessionParticipant

IUccSessionParticipant CreateParticipant (
    UccUri pUri,
    UccContext pContext
)

IUccSessionParticipant^ CreateParticipant (
    UccUri^ pUri, 
    UccContext^ pContext
)

IUccSessionParticipant CreateParticipant (
    UccUri pUri, 
    UccContext pContext
)

function CreateParticipant (
    pUri : UccUri, 
    pContext : UccContext
) : IUccSessionParticipant

Parameters

• pUri
  A value of the IUccUri* (UccUri, for a .NET application) type. This represents the SIP URI of the remote participant of the session.

• pContext
  A value of the IUccContext* (UccContext, for a .NET application) type. This specifies a set of name-value pairs as the participant context. The default value is NULL. This specifies the optional context. The NULL value is acceptable.

Return Value

A value of the IUccSessionParticipant** (IUccSessionParticipant, for a .NET application) type. This returns the newly created remote participant object.

Remarks

After successfully created, the application can set properties on the newly created participant object and then add the participant to the session to invite the remote participant to the session.

Although a client can advise for session participant events when the new participant is created, it is better to add the participant to a session and wait for the OnAddParticipant event to indicate the participant was added. The client can advise for session participant events in the event handler. A session invitation is sent to the remote user when the IUccSessionParticipant instance is added to the session.

Win32 COM/C++ Syntax

HRESULT CreateParticipant
(
   IUccUri* pUri,
   IUccContext* pContext,
   IUccSessionParticipant** ppParticipant
);

Example

The following example is drawn from an application class that wraps an instance of IUccSession (this._session). The method takes the parameters necessary to create a new session participant with specific user context. The added named properties include a property for the User string and an additional custom named property and value

/// <summary>
/// Creates a new session participant with associated
/// context metadata
/// </summary>
/// <param name="pSession">Session to create user in</param>
/// <param name="user">UccUri of remote user to add to session</param>
/// <param name="pContextKey">string property name of additional context property</param>
/// <param name="pContextValue">string value of additional context</param>
/// <param name="pEventSink">class instance to handle session participant events</param>
/// <returns>new session participant</returns>
public IUccSessionParticipant CreateSessionParticipant(
    IUccSession pSession,
    UccUri user,
    string pContextKey,
    string pContextValue,
    _IUccSessionParticipantEvents pEventSink)
{
    IUccSessionParticipant returnValue = null;
    if (pSession == null)
    {
        throw new ArgumentNullException(
            "pSession",
            "session cannot be null");
    }
    if (user == null)
    {
        throw new ArgumentNullException(
            "user", 
            "user cannot be null");
    }
    if (pEventSink == null)
    {
        throw new ArgumentNullException(
            "pEventSink",
            "event sink cannot be null");
    }
    try
    {
        //create a session participant using the passed SIP uri
        UccContext userContext = new UccContext();
        userContext.AddNamedProperty("User", user.User);
        if (pContextKey.Length > 0 && pContextValue.Length > 0)
        {
            userContext.AddNamedProperty(pContextKey, pContextValue);
        }

        //create the session participant with associated Context
        returnValue = pSession.CreateParticipant(
            user,
            userContext);

        //advise for session participant events
        UCC_Advise<_IUccSessionParticipantEvents>(
            returnValue, 
            pEventSink);
    }
    catch (COMException)
    { }
    return returnValue;

}

Thread Safety

All public static (Shared in Visual Basic) members of this type are thread-safe. Instance members are not guaranteed to be thread-safe.

Platforms

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2000 with Service Pack 4, Windows Server 2003, Windows Vista Ultimate Edition, Windows Vista Business Edition, Windows Vista Enterprise Edition

Target Platforms

See Also

Reference

IUccSession Interface
IUccSession Members
Microsoft.Office.Interop.UccApi Namespace

Other Resources

Code Listing: Basic Event Registration and Other Helper Methods in C#