IDirectPlay8Client::Send 메서드

서버에 데이터를 송신한다. 메시지는 동기 또는 비동기에 송신할 수 있다.

구문

HRESULT Send(      

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

파라미터

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
[in, out] DPNHANDLE. 메서드가 돌아오면phAsyncHandle 는,IDirectPlay8Client::CancelAsyncOperation 에 건네주어 처리를 취소할 수가 있는 핸들을 포인트 한다. dwFlags 에 DPNSEND_SYNC 플래그가 설정되어 있는 경우, 이 파라미터는 NULL 로 설정해야 한다.
dwFlags
[in] 송신 동작을 기술하는 플래그. 다음의 1 개 이상의 플래그를 설정할 수 있다.
DPNSEND_SYNC
비동기 IDirectPlay8Client::Send 요구를 취소한다.
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
자신에게 송신하는 경우, 메시지 핸들러에 DPN_MSGID_RECEIVE 시스템 메시지를 송신하지 않는다.
DPNSEND_NONSEQUENTIAL
이 플래그를 설정하지 않는 경우, 메시지는 송신순서에 타겟 애플리케이션에 전달된다. 따라서, 순서 대로가 아닌 메시지는, 결핍 하고 있는 메시지가 도착할 때까지 버퍼에 저장 할 필요가 있다. 메시지를 수신순서에 타겟 애플리케이션에 전달한다.
DPNSEND_COALESCE
DirectPlay 가 패킷을 조합해 송신할 수 있도록(듯이) 한다.

반환값

메서드가 동기를 잡으면서 처리되어 처리가 성공했을 경우는 S_OK 를 돌려준다. 디폴트에서는, 이 메서드는 비동기에게 실행되어 보통은 DPNSUCCESS_PENDING 인가, 또는 다음의 몇개의 에러값을 돌려준다.
DPNERR_INVALIDFLAGS 이 메서드에 건네진 플래그는 무효이다.
DPNERR_TIMEDOUT 마감 시간이기 때문에, 처리를 완료할 수 없었다.

주의

이 메서드는, 서버의 메시지 핸들러에 DPN_MSGID_RECEIVE 시스템 메시지를 생성한다. 데이터 버퍼는, 관련지을 수 있는 구조체의 pReceiveData 멤버에 보관 유지되고 있다.
메시지에는, 저, 보통, 고의 3 개의 우선 순위의 어느쪽이든을 설정할 수 있다. 메시지에 낮은 우선 순위 또는 높은 우선 순위를 지정하려면 dwFlags 에 적절한 플래그를 설정한다. 어느 쪽의 우선 순위 플래그도 설정하지 않았던 경우, 메시지는 보통의 우선 순위가 된다. 송신 우선 순위의 더 자세한 정보는, 「네트워킹의 기본」을 참조할것.
IDirectPlay8Client::Send 요구가 완료 하면, 송신측의 메시지 핸들러에 DPN_MSGID_SEND_COMPLETE 시스템 메시지가 송신된다. 요구의 성공 또는 실패는, 관련지을 수 있었던 구조체의 hResultCode 멤버에 보관 유지된다. dwflags 에 DPN_NOCOMPLETE 플래그를 설정 하면, 송신 완료의 시스템 메시지는 송신되지 않는다.
player가 게임에 참가해, 곧바로 복수의 메시지를 송신할 필요가 있는 경우, player는 최초로 DPNSEND_COMPLETEONPROCESS 플래그를 설정한 메시지를 송신할 필요가 있다. DPN_MSGID_SEND_COMPLETE 메시지가 돌려주어지면 애플리케이션은 메시지의 송신을 시작 할 수 있다. player가 이 처리를 실시하지 않으면 경우에 따라서는 일부의 메시지를 수신측의 큐에 넣을 필요가 있다. 도착하는 데이터가 너무 많으면 큐가 증대하는 속도가 수신측의 메시지 처리 능력을 넘는 일이 있다. 그 때문에, 데이터가 손실하는 일이 있다. 그러나, player가 게임내에 확립되면 메시지 타임 아웃 또는 GetSendQueueInfo 메서드를 사용하는 것으로, DirectPlay 쓰로틀링은 데이터 플로우를 제어한다. 더 자세한 정보는, 「네트워크 사용량의 최적화」를 참조할것.
보통, 메시지가 송신되면 즉시, 송신 완료가 송신원의 컴퓨터에 송신된다. 바꾸어 말하면 송신 완료는, 메시지가 타겟상에서 처리된 것을 반드시 의미하지 않는다. 메시지는 아직 큐내에 있을 가능성도 있다. 메시지가 타겟으로 처리된 것을 확인하려면 ,dwFlags 에 DPN_COMPLETEONPROCESS 플래그를 설정한다. 이 플래그를 설정 하면, 타겟의 메시지 핸들러가 메시지를 처리해 돌아올 때까지, 송신 완료는 송신되지 않는다.
DPNSEND_COALESCE 플래그가 dwFlags 로 설정되면 DirectPlay 는 큐로 대기하고 있는 32 개까지의 패킷을 유출하는 프레임에 결합하려고 한다. DPNSEND_COALESCE 플래그가 설정되어 있는 경우에서도, DirectPlay 는 결합을 보증하지 않는다. 큐에 복수의 메시지가 있어, 수신하는 player가 Microsoft DirectX® 9.0 이후를 실행하고 있는 경우에만, 패킷은 결합된다. 음성 패킷은 모두 결합할 수 있다. 보증 첨부 및 보증 없음의 패킷은 양쪽 모두 같은 프레임에 결합된다. 프레임이 목적지에 닿기 전에 삭제되면 프레임의 보증 첨부 부분만 재발송되어 다른 데이터는 프레임에 결합되지 않는다.
주 메서드가 돌아올 때까지는, 데이터 버퍼등의 리소스가 유효한 상태인 채로 봐서는 안 된다. 이 메서드를 비동기에게 호출하는 경우, 호출이 돌아오기 전에 DPN_MSGID_SEND_COMPLETE 메시지를 받아들여, 메시지 핸들러가 처리해 버리는 일이 있다. 메시지 핸들러가 데이터 버퍼등의 리소스를 할당 해제, 또는 무효로 했을 경우, 메서드가 불려 간 다음에 리소스가 무효가 되는 일이 있다.

DPNERR_INVALIDFLAGS	이 메서드에 건네진 플래그는 무효이다.
DPNERR_TIMEDOUT	마감 시간이기 때문에, 처리를 완료할 수 없었다.