Share via

LPWSPSENDTO 回呼函式 (ws2spi.h)

  • 發行項

LPWSPSendTo 函式會使用重迭的 I/O 將資料傳送至特定目的地。

語法

LPWSPSENDTO Lpwspsendto;

int Lpwspsendto(
  [in]  SOCKET s,
  [in]  LPWSABUF lpBuffers,
  [in]  DWORD dwBufferCount,
  [out] LPDWORD lpNumberOfBytesSent,
  [in]  DWORD dwFlags,
  [in]  const sockaddr *lpTo,
  [in]  int iTolen,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  [in]  LPWSATHREADID lpThreadId,
  [out] LPINT lpErrno
)
{...}

參數

[in] s

識別通訊端的描述項。

[in] lpBuffers

WSABUF結構的陣列指標。 每個 WSABUF 結構都包含緩衝區的指標和緩衝區的長度，以位元組為單位。 針對 Winsock 應用程式，一旦呼叫 LPWSPSendTo 函式，系統就會擁有這些緩衝區，而且應用程式可能無法存取它們。 每個 WSABUF 結構中所參考的資料緩衝區都是由系統所擁有，而且您的應用程式可能無法在呼叫的存留期記憶體取它們。

[in] dwBufferCount

lpBuffers陣列中的WSABUF結構數目。

[out] lpNumberOfBytesSent

這個呼叫所傳送位元組數目的指標。

[in] dwFlags

一組旗標，指定呼叫的進行方式。

[in] lpTo

sockaddr結構中目標通訊端位址的選擇性指標。

[in] iTolen

lpTo參數所指向之位址的大小，以位元組為單位。

[in] lpOverlapped

非重迭通訊端) 忽略 WSAOverlapped 結構的指標 (。

[in] lpCompletionRoutine

類型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

當傳送作業完成時呼叫的完成常式指標， (忽略非重迭通訊端) 。

[in] lpThreadId

提供者後續呼叫WPUQueueApc時要使用的WSATHREADID結構的指標。 提供者應該儲存參考的 WSATHREADID 結構， (在 WPUQueueApc 函式傳回之後，才儲存相同) 的指標。

[out] lpErrno

錯誤碼的指標。

傳回值

如果沒有發生錯誤，而且接收作業已立即完成， LPWSPSendTo 會 傳回零。 請注意，在此情況下，如果指定完成常式，則已經排入佇列。 否則會傳回SOCKET_ERROR的值，並在 lpErrno中提供特定的錯誤碼。 錯誤碼 WSA_IO_PENDING 指出重迭的作業已成功起始，且稍後會指出完成。 任何其他錯誤碼都表示未起始重迭的作業，而且不會發生任何完成指示。

錯誤碼 意義
WSAENETDOWN
 網路子系統失敗。
WSAEACCES
 要求的位址是廣播位址，但未設定適當的旗標。
WSAEINTR
 (封鎖) 呼叫已透過 LPWSPCancelBlockingCall取消。
WSAEINPROGRESS
 封鎖 Windows Sockets 呼叫正在進行中，或服務提供者仍在處理回呼函式。
WSAEFAULT
 lpBuffers或lpTo參數不屬於使用者位址空間，或lpTo參數太小。
WSAENETRESET
 連線已中斷，因為持續運作活動偵測作業正在進行時失敗。
WSAENOBUFS
 Windows Sockets 提供者會報告緩衝區死結。
WSAENOTCONN
 通訊端未 (連線導向通訊端) 。
WSAENOTSOCK
 描述項不是通訊端。
WSAEOPNOTSUPP
 已指定MSG_OOB，但通訊端不是資料流程樣式，例如類型SOCK_STREAM、與此通訊端相關聯的通訊網域不支援 OOB 資料、不支援MSG_PARTIAL，或通訊端是單向且僅支援接收作業。
WSAESHUTDOWN
 通訊端已關閉;在叫用LPWSPShutdown之後，無法在通訊端上使用LPWSPSendTo，以及如何設定為 SD_SEND 或 SD_BOTH。
WSAEWOULDBLOCK
 Windows NT：重迭的通訊端：有太多未處理的重迭 I/O 要求。未重迭的通訊端：通訊端標示為非封鎖，且無法立即完成傳送作業。
WSAEMSGSIZE
 通訊端是訊息導向，而且訊息大於基礎傳輸所支援的最大值。
WSAEINVAL
 通訊端尚未與 LPWSPBind系結，或未使用重迭旗標建立通訊端。
WSAECONNABORTED
 虛擬線路因逾時或其他失敗而終止。
WSAECONNRESET
 虛擬線路已由遠端重設。
WSAEADDRNOTAVAIL
 例如，遠端位址不是有效的位址 (，ADDR_ANY) 。
WSAEAFNOSUPPORT
 指定之系列中的位址無法用於此通訊端。
WSAEDESTADDRREQ
 需要目的地位址。
WSAENETUNREACH
 此時無法透過此主機連接網路。
WSA_OPERATION_ABORTED
 因為通訊端關閉，或在 LPWSPIoctl中執行 SIO_FLUSH 命令，所以已取消重迭的作業。

備註

LPWSPSendTo函式通常用於 指定的無連接通訊端，以將包含在一或多個緩衝區中的資料包傳送至lpTo參數所識別的特定對等通訊端。 即使先前已使用 LPWSPConnect 函式連線到特定位址， lpTo 仍會覆寫該特定資料包的目的地位址。 在連線導向通訊端上，會忽略 lpTo 和 iToLen 參數;在此情況下， LPWSPSendTo 函 式相當於 LPWSPSend。

如果是使用 LPWSPSocket 搭配旗標所建立的重迭通訊端 (，WSA_FLAG_OVERLAPPED) 除非 lpOverlapped 和 lpCompletionRoutine 都是 Null ，在此情況下，通訊端會被視為未重迭的通訊端。 當傳輸已取用提供的緩衝區 ( () 時，就會 (叫用完成常式或事件) 物件設定的完成指示。 如果作業未立即完成，則會透過完成常式或 LPWSPGetOverlappedResult擷取最終完成狀態。

若為非重迭通訊端，則會忽略 lpOverlapped、 lpCompletionRoutine和 lpThreadId 參數，而 LPWSPSendTo 採用 一般同步語意。 資料會從提供的緩衝區 () 複製到傳輸的緩衝區。 如果通訊端為非封鎖和資料流程導向，而且傳輸緩衝區中沒有足夠的空間， LPWSPSendTo 將只傳回部分 Windows Sockets SPI 用戶端的緩衝區。 假設有相同的緩衝區情況和封鎖通訊端， LPWSPSendTo 將會封鎖，直到所有 Windows Sockets SPI 用戶端的緩衝區內容都已取用為止。

由 lpBuffers參數指向的WSABUF結構陣列是暫時性的。 如果此作業以重迭的方式完成，服務提供者必須負責擷取這些 WSABUF 結構，然後再從這個呼叫傳回。 這可讓應用程式建置堆疊型 WSABUF 陣列。

對於訊息導向通訊端，請務必不要超過基礎傳輸的訊息大小上限，這可藉由取得通訊端選項的值來取得SO_MAX_MSG_SIZE。 如果資料太長而無法透過基礎通訊協定傳遞，則會傳回 WSAEMSGSIZE 錯誤，而且不會傳輸任何資料。

請注意， 順利完成 LPWSPSendTo 並不表示資料已成功傳遞。

iFlags參數可用來影響函式調用的行為，超出為相關聯通訊端指定的選項。 也就是說，此函式的語意是由通訊端選項和 dwFlags 參數所決定。 後者是使用位 OR 運算子搭配下列任何值來建構。

值 意義
MSG_DONTROUTE 指定資料不應受限於路由。 Windows Sockets 服務提供者可以選擇忽略此旗標。
MSG_OOB (資料流程樣式通訊端傳送 OOB 資料，例如僅SOCK_STREAM) 。
MSG_PARTIAL 指定 lpBuffers 只包含部分訊息。 請注意，不支援部分訊息傳輸的傳輸會傳回錯誤碼 WSAEOPNOTSUPP 。

 

 

如果重迭的作業立即完成， LPWSPSendTo 會傳回零的值，且 lpNumberOfBytesSent 參數會隨著傳送的位元組數目更新。 如果已成功起始重迭的作業，且稍後將會完成， LPWSPSendTo 會傳回SOCKET_ERROR並指出錯誤碼WSA_IO_PENDING。 在此情況下，不會更新 lpNumberOfBytesSent 。 當重迭的作業完成時，傳送的資料量會透過完成常式中的cbTransferred參數指出，如果指定) ，或透過LPWSPGetOverlappedResult中的lwaTransfer參數，則表示 (。

提供者必須允許從先前LPWSPRecv、LPWSPRecvFrom、LPWSPSend或LPWSPSendTo函式的完成常式內呼叫此函式。 不過，對於指定的通訊端，I/O 完成常式不能是巢狀的。 這可讓時間敏感的資料傳輸完全發生在先占式內容中。

lpOverlapped參數在重迭作業期間必須有效。 如果同時未處理多個 I/O 作業，則每個作業都必須參考個別的重迭結構。 WSAOverlapped結構是在自己的參考頁面中定義。

如果lpCompletionRoutine參數為null，當重迭的作業包含有效的事件物件控制碼時，服務提供者會發出lpOverlapped的hEvent成員訊號。 Windows Sockets SPI 用戶端可以使用 LPWSPGetOverlappedResult 來等候或輪詢事件物件。

如果 lpCompletionRoutine 不是 Null， 則會忽略 hEvent 成員，而且可由 Windows Sockets SPI 用戶端用來將內容資訊傳遞至完成常式。 將非NulllpCompletionRoutine和更新版本的用戶端針對相同的重迭 I/O 要求呼叫WSAGetOverlappedResult的用戶端，可能不會將該叫用 WSAGetOverlappedResult的fWait參數設定為TRUE。 在此情況下， 未定義 hEvent 成員的使用方式，而嘗試等候 hEvent 成員會產生無法預期的結果。

當重迭的作業完成時，服務提供者必須負責安排用戶端指定完成常式的叫用。 由於完成常式必須在起始重迭作業之相同執行緒的內容中執行，因此無法直接從服務提供者叫用。 Ws2_32.dll 提供非同步程序呼叫 (APC) 機制，以協助叫用完成常式。

服務提供者會藉由呼叫 WPUQueueApc，安排在適當的執行緒中執行的函式。 此函式可以從任何進程和執行緒內容呼叫，甚至是與用來起始重迭作業之執行緒和進程不同的內容。

WPUQueueApc函式會接受輸入參數作為WSATHREADID結構的指標， (透過lpThreadId輸入參數提供給提供者) 、要叫用的 APC 函式指標，以及後續傳遞至 APC 函式的內容值。 因為只有單一內容值可用，所以 APC 函式本身不能是用戶端指定的完成常式。 服務提供者必須改為提供自己的 APC 函式指標，該函式會使用提供的內容值來存取重迭作業所需的結果資訊，然後叫用用戶端指定的完成常式。

用戶端提供的完成常式原型如下所示。

void CALLBACK 
CompletionRoutine(  
  IN DWORD           dwError, 
  IN DWORD           cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD           dwFlags 
);

CompletionRoutine 是用戶端提供函式名稱的預留位置。 dwError 會指定重迭作業的完成狀態，如 lpOverlapped所指出。 cbTransferred 會指定傳送的位元組數目。 目前未定義旗標值， dwFlags 值將會是零。 此函式不會傳回值。

完成常式可以依任何順序呼叫，但不一定以重迭作業完成的順序相同。 不過，服務提供者保證會以所提供的相同順序傳送張貼緩衝區給用戶端。

注意

當該執行緒結束時，指定的執行緒所起始的所有 I/O 都會取消。 對於重迭的通訊端，如果執行緒在作業完成之前關閉，擱置的非同步作業可能會失敗。 如需詳細資訊，請參閱 ExitThread 。

規格需求

   
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
標頭 ws2spi.h

另請參閱

WPUQueueApc

LPWSPGetOverlappedResult

LPWSPSocket