Microsoft DirectX 8.0 (C++)

IDirectPlayVoiceClient::Connect

Connects the client to a Microsoft® DirectPlay® Voice session.

HRESULT Connect(
PDVSOUNDDEVICECONFIG pSoundDeviceConfig,
PDVCLIENTCONFIG pdvClientConfig,
DWORD dwFlags
);

Parameters

pSoundDeviceConfig
Pointer to a DVSOUNDDEVICECONFIG structure that describes the sound device configuration.
pdvClientConfig
Pointer to a DVCLIENTCONFIG structure that describes the general configuration of the client.
dwFlags
Flag. You can specify the following flag.
DVFLAGS_SYNC
The method does not return until the operation is completed.

Return Values

If the method is processed synchronously and is successful, it returns DV_OK. By default, this method is run asynchronously and returns DVERR_PENDING. On error, this method will return one of the following values.

DVERR_ALREADYPENDING
DVERR_COMPRESSIONNOTSUPPORTED
DVERR_INCOMPATIBLEVERSION
DVERR_INVALIDBUFFER
DVERR_INVALIDDEVICE
DVERR_INVALIDFLAGS
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTINITIALIZED
DVERR_OUTOFMEMORY
DVERR_RUNSETUP
DVERR_SENDERROR
DVERR_SOUNDINITFAILURE
DVERR_TIMEOUT
DVERR_TRANSPORTNOPLAYER
DVERR_TRANSPORTNOSESSION
DVERR_CONNECTED
DVERR_NOVOICESESSION

Remarks

You must test the sound devices selected for playback and capture by invoking the setup wizard before connecting the client to the DirectPlay Voice session. On application startup, check the audio configuration by using IDirectPlayVoiceTest::CheckAudioSetup. If this method returns DVERR_RUNSETUP, the sound configuration specified has not been tested. The setup wizard needs to be run only once for any configuration.

If you specify a buffer that is not the right format, the method will return DVERR_INVALIDBUFFER.

If the buffer or a portion of the buffer is locked when DirectPlay Voice attempts to write to it, the method will return DVERR_INVALIDBUFFER, and DirectPlay Voice will disconnect from the session. You will also receive a DVMSGID_SESSIONLOST message. The hResult member of the associated structure will be set to DVERR_LOCKEDBUFFER. Subsequent method calls will return a DVERR_NOTCONNECTED error code.

If full duplex operation is not supported, DirectPlay Voice falls back to half duplex (listen only) mode. To determine if you are in half-duplex mode, call IDirectPlayVoiceClient::GetSoundDeviceConfig after you have completed the connection. If you are in half-duplex mode, the dwFlags member of the DVSOUNDDEVICECONFIG structure will have the DVSOUNDCONFIG_HALFDUPLEX flag set.

Regardless of how the interfaces are obtained, the DirectPlayVoiceClient object maintains a reference, through a call to AddRef, to the IDirectSound and IDirectSoundCapture interfaces it uses until IDirectPlayVoiceClient::Disconnect is called. When Disconnect is called, the DirectPlayVoiceClient object calls Release on both interfaces.

If this method is called synchronously by setting the DVFLAGS_SYNC flag, the DVMSG_CONNECTRESULT message is not sent to the message handler. In this case, the connection result is determined by the return value of this method.

If this method is called asynchronously (by default), calling this method immediately returns a DVERR_PENDING error value and proceeds to process the connection request in the background. The status of the connection is not be known until the DirectPlay Voice client generates a DVMSG_CONNECTRESULT message with the connection result.

Any calls to IDirectPlayVoiceClient::Connect while a connection is pending return DVERR_ALREADYPENDING. Additionally, only one connection can be pending at a time.

A transport session must be started on the specified DirectPlay object before calling this method. A successful call to IDirectPlayVoiceClient::Initialize must be made before calling the Connect method.

Requirements

  Windows NT/2000: Available as a redistributable for Windows 2000 and later.
  Windows 95/98: Available as a redistributable for Windows 95 and later.
  Header: Declared in Dvoice.h.