IDirectPlay8Peer::EnumHosts 메서드

Microsoft® DirectPlay® 게임을 호스트 하는 애플리케이션을 열거한다.

구문

HRESULT EnumHosts(      

    PDPN_APPLICATION_DESC const pApplicationDesc,
    IDirectPlay8Address *const pdpaddrHost,
    IDirectPlay8Address *const pdpaddrDeviceInfo,
    PVOID const pvUserEnumData,
    const DWORD dwUserEnumDataSize,
    const DWORD dwEnumCount,
    const DWORD dwRetryInterval,
    const DWORD dwTimeOut,
    PVOID const pvUserContext,
    HANDLE *const pAsyncHandle,
    const DWORD dwFlags
);

파라미터

pApplicationDesc

[in] 열거하는 애플리케이션의 호스트를 지정하는 DPN_APPLICATION_DESC 구조체의 포인터. pApplicationDesc. dwSize 멤버를 적절한 값으로 설정할 필요가 있다. 응답수를 줄이려면 ,pApplicationDesc. guidApplication 를 검색하는 애플리케이션의 글로벌 일의 식별자 (GUID)로 설정한다. 이 멤버가 설정되지 않은 경우, 모든 애플리케이션이 검색 대상이 된다.

pdpaddrHost

[in] 애플리케이션을 호스트 하고 있는 컴퓨터의 주소를 지정하는 IDirectPlay8Address 개체의 포인터. 서비스 프로바이더에 따라서는, 이 파라미터를 NULL 로 설정하거나 서비스 프로바이더 구성 요소만 들어간 주소 개체로 설정할 수 있다. 이 경우, DirectPlay 는 브로드캐스트 메카니즘을 사용하는지,pdpaddrDeviceInfo 파라미터로부터 정보를 얻어온다. dwFlags 에 DPNENUMHOSTS_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 사용자에 결핍 하고 있는 주소 정보를 문의할 수가 있다.

pdpaddrDeviceInfo

[in] 열거에 사용하는 서비스 프로바이더 및 로컬 장치의 설정을 지정하는 IDirectPlay8Address 개체의 포인터. dwFlags 파라미터에 DPNENUMHOSTS_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 사용자에 결핍 하고 있는 주소 정보를 문의할 수가 있다.

pvUserEnumData

[in] 열거 요구로부터 호스트에게 송신되는 데이터 블록의 포인터. 데이터의 사이즈는, 네트워크의 종류에 의해 제한된다. 정확한 값을 얻어오려면,IDirectPlay8Peer::GetSPCaps 를 호출한다.

dwUserEnumDataSize

[in] pvUserEnumData 파라미터로 가리키는 데이터의 사이즈를 지정하는 DWORD 형의 변수.

dwEnumCount

[in] 열거 데이터를 송신하는 회수를 지정하는 값. 디폴트값을 사용하려면 , 이 파라미터를 0 으로 설정한다. dwEnumCount 의 디폴트값을 얻어오려면,IDirectPlay8Peer::GetSPCaps 를 호출한다. dwEnumCount 에 INFINITE 가 지정되었을 경우, 열거는 삭제될 때까지 속행된다.

dwRetryInterval

[in] 열거의 재시행의 간격을 밀리 세컨드 단위로 지정하는 값. 디폴트값을 사용하려면 , 이 파라미터를 0 으로 설정한다. dwRetryInterval 의 디폴트값을 얻어오려면,IDirectPlay8Peer::GetSPCaps 를 호출한다.

dwTimeOut

[in] 마지막 열거가 송신된 후, DirectPlay 가 응답을 기다리는 시간 (밀리 세컨드)을 지정하는,DWORD 형의 변수. 디폴트값을 사용하려면 , 이 파라미터를 0 으로 설정한다. dwTimeOut 의 디폴트값을 얻어오려면,IDirectPlay8Peer::GetSPCaps 를 호출한다. INFINITE 가 지정되었을 경우, 열거는 삭제될 때까지 속행된다.

pvUserContext

[in] 열거에의 응답과 함께 불려 갔을 경우에, 피어의 메시지 핸들러에 제공되는 문맥. 동시 실행되고 있는 열거의 응답을 구별하는 경우에 도움이 된다.

pAsyncHandle

[out] DPNHANDLE. 메서드가 값을 돌려주면pAsyncHandle 은,IDirectPlay8Peer::CancelAsyncOperation 에 건네주어 처리를 취소할 수가 있는 핸들을 포인트 한다. dwFlags 에 DPNENUMHOSTS_SYNC 플래그가 설정되어 있는 경우, 이 파라미터는 NULL 로 설정해야 한다.

dwFlags

[in] 다음의 플래그를 설정할 수 있다.

DPNENUMHOSTS_SYNC

메서드를 동기를 잡으면서 처리한다.

DPNENUMHOSTS_OKTOQUERYFORADDRESSING

이 플래그를 설정 하면, DirectPlay 의 표준 다이알로그 박스가 표시된다. 충분한 정보가 이 메서드에 건네지지 않은 경우는, 상세한 것에 대하여 사용자에 문의한다.

DPNENUMHOSTS_NOBROADCASTFALLBACK

서비스 프로바이더가 있는 요소를 전요소에 복사 하는 것을 지원 하고 있는 경우, 이 플래그를 설정 하면 있는 요소를 전요소에 복사 하는 기능이 무효가 된다. 이 플래그를 설정하기 전에 DPN_SP_CAPS 구조체를 조사해 있는 요소를 전요소에 복사 하는 것이 지원 되고 있는지를 확인하는 것.

반환값

메서드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메서드는 비동기에게 실행되어 보통의 경우,DPNSUCCESS_PENDING 를 돌려준다. 또, 다음의 몇개의 에러값을 돌려주는 경우도 있다.

DPNERR_INVALIDDEVICEADDRESS	로컬 컴퓨터 또는 어댑터의 주소가 무효이다.
DPNERR_INVALIDFLAGS	이 메서드에 건네진 플래그는 무효이다.
DPNERR_INVALIDHOSTADDRESS	지정된 리모트 주소가 무효이다.
DPNERR_INVALIDPARAM	메서드에 건네진 1 개 혹은 복수의 파라미터가 무효이다.
DPNERR_ENUMQUERYTOOLARGE	지정된 쿼리 데이터가 너무 크다.
DPNERR_USERCANCEL	사용자는 처리를 취소했다.

주의

열거 기준을 채우는 애플리케이션이 발견되면DPN_MSGID_ENUM_HOSTS_RESPONSE 시스템 메시지에 의해 애플리케이션의 메시지 핸들러가 호출된다. 메시지에는, 발견된 애플리케이션을 기술하는 DPN_APPLICATION_DESC 구조체 및 호스트의 장소를 식별하는 IDirectPlay8Address 개체가 들어가 있다.

Transmission Control Protocol/Internet Protocol (TCP/IP) 서비스 프로바이더를 사용할 때에 네트워크 어드레스 변환 (NAT)과 프록시의 지원을 향상시키는지, 모뎀 서비스 프로바이더에 의한 리다이얼을 피하는 경우는, 열거를 액티브하게 해 IDirectPlay8Peer::Connect 메서드를 호출하는 것. 열거가 완료하는 것을 피하려면 ,dwEnumCount 파라미터를 INFINITE 로 설정해, 접속 처리가 완료하기 전에 열거가 끝나지 않게 하기 위한(해) IDirectPlay8Peer::CancelAsyncOperation 를 사용하지 않는다. 또, DPNMSG_ENUM_HOSTS_RESPONSE 메시지의 pAddressSender 및 pAddressDevice 주소 개체를 변경하지 않고 IDirectPlay8Peer::Connect 메서드의 파라미터 pHostAddr 및 pDeviceInfo 에 건네준다. 콜백 함수의 외측에서 주소 개체를 IDirectPlay8Peer::Connect 에 건네주려면 ,IDirectPlay8Address::Duplicate 또는 IDirectPlay8Address::AddRef 를 사용해 개체의 파기를 막아, thread에 의존하지 않는 코드를 사용해 포인터를 보존한다.

임의의 수의 열거를 동시에 실행할 수 있다. 다른 복수의 열거에의 응답을 구별하기 위해서,pvUserContext 의 값이 메시지 핸들러에 제공된다.

열거의 처리에는 다양한 방법이 있기 (위해)때문에, 미디어에 관해서 특히 지식이 없는 한, 애플리케이션에서는 dwEnumCount,dwRetryInterval, 또는 dwTimeOut 를 지정하지 않는 것. 유일한 예외로서 명시적으로 삭제될 때까지 열거를 계속시키고 싶은 경우는,dwEnumCount 를 INFINITE 로 설정한다.

디폴트의 열거 카운트값과 타임 아웃값으로,IDirectPlay8Peer::EnumHosts 는 적절한 시간내에 종료한다. 이러한 값은 서비스 프로바이더에 의해 설정되어IDirectPlay8Peer::GetSPCaps 를 호출해 취득할 수 있다. 비동기의 열거는,IDirectPlay8Peer::CancelAsyncOperation 를 호출하는지, 또는 dwFlags 파라미터에 pAsyncHandle 파라미터에 돌려주어진 핸들러를 건네줄까 DPNCANCEL_ENUM 플래그를 설정하면, 언제라도 정지할 수 있다. DPN_MSGID_ENUM_HOSTS_RESPONSE 메시지를 처리 할 때 메시지 핸들러로부터 S_OK 이외의 값을 돌려주는 것도, 열거는 정지할 수 있다.

1 개의 열거 세션중에 같은 호스트로부터 복수의 DPN_MSGID_ENUM_HOSTS_RESPONSE 메시지를 받아들이는 일이 있다. 관련하는 DPN_APPLICATION_DESC 구조체의 guidInstance 멤버를 사용해 이러한 중복 하는 응답을 대응시킬 수가 있다.

dwFlags 에 DPNENUMHOSTS_OKTOQUERYFORADDRESSING 플래그를 설정했을 경우, 서비스 프로바이더는, 다이알로그 박스를 표시해, 사용자에 주소 정보의 입력을 요구하려고 한다. 서비스 프로바이더가 다이알로그 박스의 표시를 시도할 때는, 표시 가능한 윈도우가 존재하고 있을 필요가 있다. 윈도우가 없는 경우, 애플리케이션은 잠근다.

「데이터값의 개요」에서는, 각 서비스 프로바이더에 필요한 주소 정보를 지정하고 있다.

IDirectPlay8Peer::CancelAsyncOperation 메서드를 호출해 열거를 취소했을 경우, 또는DPN_MSGID_ENUM_HOSTS_RESPONSE 메시지의 처리중에 DPN_OK 가 돌려주어지지 않은 경우,DPNERR_USERCANCEL 를 돌려준다.