This documentation is archived and is not being maintained.

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)

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.

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
);
Cc667993.note(en-us,office.12).gifNote:
In a Win32 application, the return value of a method or property is always an HRESULT value indicating the status of the call to the interface member. Any result of the operation is returned as a parameter marked with the [out, retval] attribute. In contrast, in a .NET application the HRESULT value indicating an error condition is returned as a COM exception and the [out, retval] parameter becomes the return value. For the UCC API-defined HRESULT values, see Trace and Handle Errors in Unified Communications Client API.

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;

}

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

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

Show: