Microsoft DirectX 9.0

IDirectPlayVoiceClient::Connect Method

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


HRESULT Connect(      

    PDVSOUNDDEVICECONFIG pSoundDeviceConfig,     PDVCLIENTCONFIG pdvClientConfig,     DWORD dwFlags );


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

Return Value

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

DVERR_ALREADYPENDINGAn asynchronous call of this type is already pending.
DVERR_COMPRESSIONNOTSUPPORTEDThe specified compression type is not supported on the local computer.
DVERR_INCOMPATIBLEVERSIONThe client connected to a voice session that is incompatible with the host.
DVERR_INVALIDDEVICEThe specified device is invalid.
DVERR_INVALIDFLAGSThe flags passed to this method are invalid.
DVERR_INVALIDOBJECTThe DirectPlay object pointer is invalid.
DVERR_INVALIDPARAMOne or more of the parameters passed to the method are invalid.
DVERR_INVALIDPOINTERThe pointer specified is invalid.
DVERR_NOTINITIALIZEDThe IDirectPlayVoiceClient::Initialize or IDirectPlayVoiceServer::Initialize method must be called before calling this method.
DVERR_OUTOFMEMORYThere is insufficient memory to perform the requested operation.
DVERR_RUNSETUPThe specified audio configuration has not been tested. Call the IDirectPlayVoiceTest::CheckAudioSetup method.
DVERR_SENDERRORAn error occurred while sending data.
DVERR_SOUNDINITFAILUREA failure was encountered initializing the sound card.
DVERR_TIMEOUTThe operation could not be performed in the specified time.
DVERR_TRANSPORTNOPLAYERThe specified transport is connected/hosting but no local player exists.
DVERR_TRANSPORTNOSESSIONThe specified transport is valid but is not connected/hosting.
DVERR_CONNECTEDThe DirectPlay Voice object is connected.
DVERR_NOVOICESESSIONThe session specified is not a voice session.


If you call this method asynchronously and it returns DVERR_PENDING, you will receive a DVMSGID_CONNECTRESULT message with the result of the connection attempt. This message can arrive before or after the method returns DVERR_PENDING. If you call this method asynchronously, you will not receive a DVMSGID_CONNECTRESULT message.

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 DVSOUNDDEVICECONFIG structure's dwFlags member 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 IDirectPlayVoiceClient::Disconnect is called, the DirectPlayVoiceClient object calls Release on both interfaces.

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.

© 2002 Microsoft Corporation. All rights reserved.