IDirectPlay8Server::SendTo 메서드

세션내의 클라이언트 또는 그룹에 데이터를 송신한다. 메시지는 동기 또는 비동기에 송신할 수 있다.

구문

HRESULT SendTo(      

    const DPNID dpnid,
    const DPN_BUFFER_DESC *const pBufferDesc,
    const DWORD cBufferDesc,
    const DWORD dwTimeOut,
    void *const pvAsyncContext,
    DPNHANDLE *const phAsyncHandle,
    const DWORD dwFlags
);

파라미터

dpnid

[in] 데이터를 수신하는 클라이언트 또는 그룹의 식별자. 세션내의 모든 player에 메시지를 송신하는 경우는, 이 파라미터를 DPNID_ALL_PLAYERS_GROUP 로 설정한다.

pBufferDesc

[in] 송신하는 데이터를 기술하는 DPN_BUFFER_DESC 구조체의 포인터.

cBufferDesc

[in] pBufferDesc 가 가리키는 DPN_BUFFER_DESC 구조체의 수. 이 버전의 Microsoft® DirectPlay® 에서는, 버퍼는 8 개까지 사용할 수 있다.

dwTimeOut

[in] 메시지의 송신을 기다리는 시간 (밀리 세컨드 단위). 메시지가 dwTimeOut 값으로 송신되지 않은 경우, 메시지는 송신 큐로부터 삭제된다. 이 파라미터를 0 으로 설정 하면, 메시지는, 송신될까 링크가 절단 될 때까지, 송신 큐에 남는다.

pvAsyncContext

[in] 사용자 지정의 문맥의 포인터. 이것은,DPN_MSGID_SEND_COMPLETE 시스템 메시지의 pvUserContext 멤버에 반환된다.

phAsyncHandle

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

dwFlags

[in] 송신 동작을 기술하는 플래그. 다음의 1 개 혹은 복수의 플래그를 설정할 수 있다.

DPNSEND_SYNC

비동기 IDirectPlay8Server::SendTo 요구를 취소한다.

DPNSEND_NOCOPY

DPN_BUFFER_DESC 구조체의 데이터를 사용해, 내부 복사는 실시하지 않는다. 데이터를 송신하는 방법으로서는 보다 효율적인 경우가 있다. 그러나,DPN_MSGID_SEND_COMPLETE 메시지를 수신하기까지 데이터의 변경이나 삭제를 실시하면, 잘못한 데이터를 송신하는 일이 있기 (위해)때문에, 견뢰한 것은 없어진다. 이 플래그를 DPNSEND_NOCOMPLETE 와 함께 사용할 수 없다.

DPNSEND_NOCOMPLETE

메시지 핸들러에 DPN_MSGID_SEND_COMPLETE 구조체를 송신하지 않는다. 이 플래그를 DPNSEND_NOCOPY 또는 DPNSEND_GUARANTEED 와 함께 사용할 수 없다. 또, 이 플래그를 사용하는 경우,pvAsyncContext 는 NULL 이어야 한다.

DPNSEND_COMPLETEONPROCESS

메시지가 타겟으로 전달되어 메시지의 수신을 나타내는 타겟의 메시지 핸들러가 돌려주어질 때,DPN_MSGID_SEND_COMPLETE 를 메시지 핸들러에 송신한다. 이 플래그가 설정되었을 경우는, 여분의 내부 메시지의 오버헤드가 있어, 메시지의 송신 처리가 현저하게 저하하는 일이 있다. 이 플래그를 설정하는 경우는, DPNSEND_GUARANTEED 도 설정할 필요가 있다.

DPNSEND_GUARANTEED

보증된 전달 방법에 의해, 메시지를 송신한다.

DPNSEND_PRIORITY_HIGH

메시지의 우선 순위를 높게 설정한다. 이 플래그는, DPNSEND_PRIORITY_LOW 와 함께 사용할 수 없다.

DPNSEND_PRIORITY_LOW

메시지의 우선 순위를 낮게 설정한다. 이 플래그는, DPNSEND_PRIORITY_HIGH 와 함께 사용할 수 없다.

DPNSEND_NOLOOPBACK

로컬 player를 포함한 그룹에 송신하고 있을 때, 메시지 핸들러에의 DPN_MSGID_RECEIVE 시스템 메시지를 억제한다. 예를 들어, 세션 전체에 있는 요소를 전요소에 복사 하는 경우는, 이 플래그가 편리하다.

DPNSEND_NONSEQUENTIAL

이 플래그가 설정되었을 경우, 타겟 애플리케이션은, 사용자의 컴퓨터에 도착한 순서에 메시지를 받아들인다. 이 플래그가 설정되지 않은 경우, 메시지는 시퀀셜에 전달되어 타겟 애플리케이션은 송신된 순서에 메시지를 받아들인다. 따라서, 착신한 메시지를, 결핍 하고 있는 메시지가 도착할 때까지 버퍼에 저장 하는 경우가 있다.

DPNSEND_COALESCE

DirectPlay 가 패킷을 조합해 송신할 수 있도록(듯이) 한다.

반환값

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

DPNERR_CONNECTIONLOST	데이터의 송신중에 서비스 프로바이더 접속이 리셋 되었다.
DPNERR_INVALIDFLAGS	이 메서드에 건네진 플래그는 무효이다.
DPNERR_INVALIDPARAM	메서드에 건네진 1 개 혹은 복수의 파라미터가 무효이다.
DPNERR_INVALIDPLAYER	player ID 가, 이 게임 세션에 대한 유효한 player ID 로서 인식되지 않다.
DPNERR_TIMEDOUT	마감 시간이기 때문에, 처리를 완료할 수 없었다.

주의

이 메서드는, 수신측의 메시지 핸들러에 DPN_MSGID_RECEIVE 시스템 메시지를 생성한다. 데이터는, 관련지을 수 있는 구조체의 pReceiveData 멤버에 보관 유지되고 있다.

메시지에는, 저, 보통, 고의 3 개의 우선 순위의 어느쪽이든을 설정할 수 있다. 메시지에 낮은 우선 순위 또는 높은 우선 순위를 지정하려면 dwFlags 에 해당하는 플래그를 설정한다. 어느 쪽의 우선 순위 플래그도 설정하지 않았던 경우, 메시지는 보통의 우선 순위가 된다. 송신 우선 순위의 더 자세한 정보는, 「네트워킹의 기본」을 참조할것.

IDirectPlay8Server::SendTo 요구가 완료 하면, 송신측의 메시지 핸들러에 DPN_MSGID_SEND_COMPLETE 시스템 메시지가 송신된다. 요구의 성공 또는 실패는, 관련지을 수 있었던 구조체의 hResultCode 멤버에 보관 유지된다. dwFlags 에 DPNSEND_NOCOMPLETE 플래그를 설정 하면, 송신 완료의 시스템 메시지는 송신되지 않는다.

보통, 메시지가 송신되면 즉시, 송신 완료가 송신원의 컴퓨터에 송신된다. 바꾸어 말하면 송신 완료는, 메시지가 타겟상에서 처리된 것을 반드시 의미하지 않는다. 메시지는 아직 큐내에 있을 가능성도 있다. 메시지가 타겟으로 처리된 것을 확인하려면 ,dwFlags 에 DPNSEND_COMPLETEONPROCESS 플래그를 설정한다. 이 플래그를 설정 하면, 타겟의 메시지 핸들러가 메시지를 처리해 돌아올 때까지, 송신 완료는 송신되지 않는다.

DPNSEND_COALESCE 플래그가 dwFlags 로 설정되면 DirectPlay 는 큐로 대기하고 있는 32 개까지의 패킷을, 유출하는 프레임에 결합하려고 한다. DPNSEND_COALESCE 플래그가 설정되어 있는 경우에서도, DirectPlay 는 결합을 보증하지 않는다. 큐에 복수의 메시지가 있어, 수신하는 player가 Microsoft DirectX® 9.0 이후를 실행하고 있는 경우에만, 패킷은 결합된다. 음성 패킷은 모두 결합할 수 있다. 보증 첨부 및 보증 없음의 패킷은 양쪽 모두 같은 프레임에 결합된다. 프레임이 목적지에 닿기 전에 삭제되면 프레임의 보증 첨부 부분만 재발송되어 다른 데이터는 프레임에 결합되지 않는다.

주  메서드가 돌아올 때까지는, 데이터 버퍼등의 리소스가 유효한 상태인 채로 봐서는 안 된다. 이 메서드를 비동기에게 호출하는 경우, 호출이 돌아오기 전에 DPN_MSGID_SEND_COMPLETE 메시지를 받아들여, 메시지 핸들러가 처리해 버리는 일이 있다. 메시지 핸들러가 데이터 버퍼등의 리소스를 할당 해제, 또는 무효로 했을 경우, 메서드가 불려 간 다음에 리소스가 무효가 되는 일이 있다.