LPWSPSEND 回呼函式 (ws2spi.h)

發行項
08/28/2023

LPWSPSend函式會在連接的通訊端上傳送資料。

語法

LPWSPSEND Lpwspsend;

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

參數

[in] s

識別已連線通訊端的描述項。

[in] lpBuffers

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

[in] dwBufferCount

lpBuffers陣列中的WSABUF結構數目。

[out] lpNumberOfBytesSent

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

[in] dwFlags

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

[in] lpOverlapped

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

[in] lpCompletionRoutine

類型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

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

[in] lpThreadId

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

[out] lpErrno

錯誤碼的指標。

傳回值

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

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

備註

LPWSPSend函式是用來從s所指定連接導向通訊端上的一或多個緩衝區寫入傳出資料。不過，它也可用於透過 LPWSPConnect 函式所建立之預設對等位址的無連線通訊端。

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

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

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

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

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

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

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

如果重迭的作業立即完成， LPWSPSend 會傳回零的值，且 lpNumberOfBytesSent 參數會以傳送的位元組數目更新。如果已成功起始重迭的作業，且稍後會完成， LPWSPSend 會傳回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 用戶端用來將內容資訊傳遞至完成常式。將非 Null lpCompletionRoutine和更新版本的用戶端針對相同的重迭 I/O 要求呼叫WSAGetOverlappedResult的用戶端，可能不會將該叫用 WSAGetOverlappedResult的fWait參數設定為TRUE。在此情況下， 未定義 hEvent 成員的使用方式，而嘗試等候 hEvent 成員會產生無法預期的結果。

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

服務提供者會藉由呼叫 WPUQueueApc，安排在適當的執行緒中執行的函式。請注意，在相同進程的內容中，必須叫用此函式 (，但不一定叫用用來起始重迭作業的相同執行緒) 。服務提供者必須負責在呼叫 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

共用方式為

LPWSPSEND 回呼函式 (ws2spi.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

其他資源