Call Object

INmCall::Accept

HRESULT Accept(void);

Accepts an invitation to a conference.

Returns S_OK if successful, or E_FAIL if the call state is not NM_CALL_RING.

This method is only valid for incoming calls while the call state equals NM_CALL_RING.

This method will trigger an NM_CALL_ACCEPTED notification if successful.

The application should monitor INmCallNotify::StateChanged for the current conference state.

INmCall::Cancel

HRESULT Cancel(void);

Cancels the request to join a conference or cancels placement of a call.

Returns S_OK if successful, or returns E_FAIL if it is an incoming call. (Incoming calls cannot be canceled. They require use of the INmCall::Accept or INmCall::Reject method.)

INmCall::GetAddr

HRESULT GetAddr(
    [out] BSTR *pbstrAddr,
    [out] NM_ADDR_TYPE *puType);

Retrieves the address information of the person being called if this is an outgoing call. Retrieves the address of the remote computer if this is an incoming call.

Returns one of the following values:

S_OK Success.
E_POINTER pbstrAddr is an invalid pointer, or puType is invalid.
E_FAIL Internal resources are not available.

pbstrAddr

Pointer to a BSTR that contains the local user's name or address.

puType

Pointer to an NM_ADDR_TYPE that identifies the type of the user name or address. This can be one of the following:

NM_ADDR_H323_GATEWAY	IP address of the gateway server and the phone number (www.xxx.yyy.zzz/number). Also see INmManager::CreateCall.
NM_ADDR_IP	IP address.
NM_ADDR_MACHINENAME	Machine name.
NM_ADDR_ULS	ILS server name and the e-mail name (server/e-mail).
NM_ADDR_UNKNOWN	Unknown type.

The information retrieved by this method may not be available if the call does not have data capabilities (is audio/video only) or if the local or remote computer is running NetMeeting 2.0 or earlier.

INmCall::GetConference

HRESULT GetConference(
    [out] INmConference **ppConference);

Retrieves a pointer to an INmConference Interface on the current Conference object.

Returns one of the following values:

S_OK Success.
S_FALSE There is no conference associated with the call.
E_POINTER The ppConference pointer is invalid.

ppConference: Pointer to a pointer to the INmConference Interface on the Conference object.

When this method is successfully called (returns S_OK), the calling application must call Release on the resulting conference pointer when finished.

If no conference is currently associated with the call, this method will return S_FALSE and the conference object will be set to NULL.

INmCall::GetName

HRESULT GetName(
    [out] BSTR *pbstrName);

Retrieves information about the remote user if it is available. If the call is incoming, this method retrieves the remote user's name. If the call is outgoing, this method retrieves the remote user's address (computer name or IP address).

Returns one of the following values:

S_OK Success.
E_POINTER pbstrName is an invalid pointer.
E_FAIL Internal resources are not available.

pbstrName: Pointer to a BSTR containing the name or address of the user.

INmCall::GetState

HRESULT GetState(
    [out] NM_CALL_STATE *pState);

Retrieves the state of the call.

Returns one of the following values:

S_OK Success.
E_POINTER pState is an invalid pointer.
E_FAIL Internal resources are not available.

pState

NM_CALL_STATE that identifies the call state. Constants include:

NM_CALL_ACCEPTED	The call has been accepted.
NM_CALL_CANCELED	The call has been canceled.
NM_CALL_INIT	The call is being initialized.
NM_CALL_INVALID	The call is invalid.
NM_CALL_REJECTED	The call was rejected or ignored.
NM_CALL_RING	The incoming call is waiting for a response. (For more information, see INmCall::Accept and INmCall::Reject.)
NM_CALL_SEARCH	The outgoing call is in the process of finding the destination address.
NM_CALL_WAIT	The outgoing call is waiting for a response from the remote system.

INmCall::GetUserData

HRESULT GetUserData(
    [in] REFGUID rguid,
    [out] BYTE **ppb,
    [out] ULONG *pcb);

Retrieves information about a user that is associated with a specific globally unique identifier (GUID).

This method is not yet implemented.

Returns one of the following values:

S_OK Success.
E_POINTER The ppb or pcb pointer is invalid.
E_INVALIDARG The rguid parameter is invalid.
E_FAIL Internal resources are not available.

rguid: GUID of the user data to retrieve.
ppb: Pointer to a pointer to the data.
pcb: Pointer to the size of the data.

INmCall::IsIncoming

HRESULT IsIncoming(void);

Determines if the Call object represents an incoming call or an outgoing call.

Returns S_OK if the call is incoming, or S_FALSE if the call is outgoing.

INmCall::Reject

HRESULT Reject(void);

Rejects an invitation to a conference.

Returns S_OK if successful, or E_FAIL if the call state is not NM_CALL_RING or if the call is not incoming.

This method is valid for incoming calls only while the call state equals NM_CALL_RING.

Accepted
Failed
NmUI
StateChanged

INmCallNotify Interface

This is an event notification sink interface for the INmCall interface. The methods in this interface are called by the Call object when specific events occur.

These event sink methods should be defined and implemented by the client application to respond to notifications from a Call object. For example, the INmCallNotify::StateChanged method is notified when the status (which includes a variety of states) of a call has changed. The client application implementation of this method could provide a display to the user for each of these state changes when they occur.

The application must be in control of the NetMeeting user interface (it must have successfully initialized with NM_INIT_CONTROL) for it to be notified of incoming calls.

INmCallNotify::Accepted

HRESULT Accepted(
    [in] INmConference *pConference);

Indicates that a call attempt has been accepted into the conference.

This event sink should always return S_OK to the event source.

pConference: Pointer to an INmConference Interface on the Conference object.

This method is notified only when the remote computer has accepted a call. When the local computer accepts a call an INmCallNotify::StateChanged notification is triggered.

INmCallNotify::Failed

HRESULT Failed(
    [in] ULONG uError);

Indicates that a call attempt has failed.

This event sink should always return S_OK to the event source.

uError

ULONG that identifies the reason for the failed call. Constants include:

NM_CALLERR_AUDIO	Audio connection failed.
NM_CALLERR_AUDIO_LOCAL	Local audio device already in use.
NM_CALLERR_AUDIO_REMOTE	Remote audio device in use.
NM_CALLERR_CONFERENCE_NAME	Problem with the conference name.
NM_CALLERR_IN_CONFERENCE	Remote system is in a conference.
NM_CALLERR_MCU	Can't invite a multipoint control unit into an existing conference.
NM_CALLERR_MEDIA	Invalid channel/media types.
NM_CALLERR_NAME_RESOLUTION	Name resolution failed.
NM_CALLERR_NOT_FOUND	User/Address not found.
NM_CALLERR_NOT_INITIALIZED	Local system not initialized.
NM_CALLERR_PASSWORD	Invalid conference password. Password-protected conferences are currently unsupported.
NM_CALLERR_REJECTED	Remote system rejected the request.
NM_CALLERR_UNKNOWN	Unknown call error.

INmCallNotify::NmUI

HRESULT NmUI(
    [in] CONFN uNotify);

Receives event notification when a call change occurs. Only the application in charge (initialized with NM_INIT_CONTROL) of the NetMeeting user interface will receive these notifications.

This event sink should always return S_OK to the event source.

uNotify

Identifier of an event constant during a call. Constants include:

CONFN_CALL_FAILED	The call failed.
CONFN_CALL_IGNORED	The call was ignored (user selected "Ignore" or the pop-up dialog timed out).
CONFN_CALL_IN_CONFERENCE	The remote system is already in a conference.
CONFN_CALL_INCOMPATIBLE	The remote version of NetMeeting is not compatible with the local system.
CONFN_CALL_NEWER	The remote system is a newer version of NetMeeting than the local one.
CONFN_CALL_OLDER	The remote system is an older version of NetMeeting (for example, NetMeeting 2.1 calling NetMeeting 2.0 or 1.0).

INmCallNotify::StateChanged

HRESULT StateChanged(
    [in] NM_CALL_STATE uState);

Indicates that the status of a call has changed.

This event sink should always return S_OK to the event source.

uState

NM_CALL_STATE that identifies the current state. Constants include:

NM_CALL_ACCEPTED	The call has been accepted.
NM_CALL_CANCELED	The call has been canceled. See the version change information in the comments at the end of this reference.
NM_CALL_INIT	The call is being initialized.
NM_CALL_INVALID	The call is invalid.
NM_CALL_REJECTED	The call was rejected or ignored. See the version change information in the comments at the end of this reference.
NM_CALL_RING	The incoming call is waiting for a response. (For more information, see INmCall::Accept and INmCall::Reject).
NM_CALL_SEARCH	The outgoing call is in the process of finding the destination address.
NM_CALL_WAIT	The outgoing call is waiting for a response from the remote system.

A Call object will not produce state change notifications after an NM_CALL_REJECTED, NM_CALL_ACCEPTED, or NM_CALL_CANCELED state occurs. The Call object may be released after one of these notifications.

A successful outgoing call moves through the following states, in this order: NM_CALL_INIT, NM_CALL_SEARCH, NM_CALL_WAIT, NM_CALL_ACCEPTED.

A successful incoming call moves through the following states, in this order: NM_CALL_INIT, NM_CALL_RING, NM_CALL_ACCEPTED.

For NetMeeting 2.1, the uState parameter received will be NM_CALL_CANCELED when an invalid computer name or address is passed to INmManager::CallConference or INmManager::CreateCall. Previous versions of NetMeeting resulted in NM_CALL_REJECTED for uState.