Share via

IUccSession.AddParticipant Method

  • Article

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.

Raised when an AddParticipant request is processed. Adds a new participant to the session.

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

Syntax

'Declaration
Sub AddParticipant ( _
    pParticipant As IUccSessionParticipant, _
    pOperationContext As UccOperationContext _
)

void AddParticipant (
    IUccSessionParticipant pParticipant,
    UccOperationContext pOperationContext
)

void AddParticipant (
    IUccSessionParticipant^ pParticipant, 
    UccOperationContext^ pOperationContext
)

void AddParticipant (
    IUccSessionParticipant pParticipant, 
    UccOperationContext pOperationContext
)

function AddParticipant (
    pParticipant : IUccSessionParticipant, 
    pOperationContext : UccOperationContext
)

Parameters

  • pParticipant
    A value of the IUccSessionParticipant* (IUccSessionParticipant, for a .NET application) type. This specifies a remote participant to be added to the session.
  • pOperationContext
    A value of the IUccOperationContext* (UccOperationContext, for a .NET application) type. The default value is NULL. This specifies the optional operation context. The NULL value is acceptable.

Remarks

An application can catch this event to determine whether the server has finished processing the request to add the remote participant to the session. The Participants collection exposed by the pEventSource parameter includes the newly added participant. The collection is sorted in a 'first in, first out' order so the new participant is collection item at the end of the collection.

IUccSessionParticipant p = pEventSource.Participants[pEventSource.Participants.Count] as IUccSessionParticipant; returns the newest collection member.

Win32 COM/C++ Syntax

HRESULT OnAddParticipant
(
   IUccSession* pEventSource,
   IUccOperationProgressEvent* pEventData
);

Note

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.

Remarks

The context parameter identifies additional information related to the new participant addition. Attempts to add an existing participant results in an error. A call to AddParticipant causes the OnAddParticipant event to be raised by the current session object if the participant was added.

If the session is a transmission-free session such as a conference session, all session participant endpoints receive OnParticipantAdded to notify each local client of the new session participant.

The operation context provided by the call to AddParticipant is available to the OnAddParticipant method to allow a client application to access contextual meta data describing the add operation.

An instance of IUccSession acts as a factory for new session participants. Before adding a session participant, the participant must be created with a call to CreateParticipant.

Note

A peer-to-peer session supports only two users. If more than two users are to participate, a conference session must be scheduled and participants invited. Each invited participant enters the conference by calling Enter on an instance of IUccConferenceSession.

Win32 COM/C++ Syntax

HRESULT AddParticipant
(
   IUccSessionParticipant* pParticipant,
   IUccOperationContext* pOperationContext
);

Note

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.

Example

The following event handler is called when a participant is added to a session. This example handler gets the newest participant added to the Participants collection and displays that user's SIP address on the local user's system console.

/// <summary>
/// callback function to handle OnAddParticipant event
/// </summary>
/// <param name="pEventSource">session participant was added to</param>
/// <param name="pEventData">relevant event data</param>
void _IUccSessionEvents.OnAddParticipant(
    IUccSession pEventSource,
    IUccOperationProgressEvent pEventData)
{
    IUccSessionParticipant p = pEventSource.Participants[pEventSource.Participants.Count] as IUccSessionParticipant;
    Console.WriteLine("Newest Participant " + p.Uri.UserAtHost);
}

Example

The following example method creates a new session participant, context, and operation context. The new session participant is added to the session (this._session) wrapped by this application class. Finally, the added session participant is advised of the current class (this) as the event sink for participant events raised by the new session participant.

/// <summary>
/// Adds a participant to the current session (this._session)
/// </summary>
/// <param name="u">UccUri representing the user to be added</param>
/// <returns>true if participant was created and the client
/// succeeded in calling AddParticipant</returns>
public Boolean addParticipant(UccUri u)
{

    //create a session participant using the passed SIP uri
    IUccSessionParticipant p = this._session.CreateParticipant(
        u,
        null);

    //advise new session participant of the current class as event sink
    UCC_Advise<_IUccSessionParticipantEvents>(
        p,
        this);

    //create a new context instance for the add operation
    UccContext pContext = new UccContextClass();

    //create new operation context
    UccOperationContext operationContext = new UccOperationContext();

    //initialize with previously created context
    operationContext.Initialize(1, pContext);

    //Add the new participant to the session
    this._session.AddParticipant(p, operationContext);
    return true;
}

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#