SIO_ASSOCIATE_PORT_RESER加值稅ION控制項程式碼

發行項
06/13/2023

描述

SIO_ASSOCIATE_PORT_RESER加值稅ION控制項程式碼會將通訊端與埠保留權杖所識別之 TCP 或 UDP 區塊的持續性或執行時間保留產生關聯。此 IOCTL 必須在通訊端系結之前發出。如果和通訊端系結時，指派給它的埠將會從指定權杖所識別的埠保留區中選取。如果沒有埠可從指定的保留區取得，系結函式呼叫將會失敗。

若要執行這項作業，請使用下列參數呼叫 WSAIoctl 或 WSPIoctl 函式。

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

參數

s

識別通訊端的描述項。

dwIoControlCode

作業的控制程式代碼。針對此作業使用 SIO_ASSOCIATE_PORT_RESER加值稅ION 。

lpvInBuffer

輸入緩衝區的指標。此參數包含與通訊端建立關聯的 TCP 或 UDP 埠保留權杖之 INET_PORT_RESER加值稅ION_TOKEN 結構的指標。

cbInBuffer

輸入緩衝區的大小，以位元組為單位。此參數必須至少是 INET_PORT_RESER加值稅ION_TOKEN 結構的大小。

lpvOutBuffer

輸出緩衝區的指標。這個作業未使用此參數。

cbOutBuffer

輸出緩衝區的大小，以位元組為單位。此參數必須設定為零。

lBytesReturned

變數的指標，可接收儲存在輸出緩衝區中的資料大小，以位元組為單位。

如果輸出緩衝區太小，則呼叫會失敗， WSAGetLastError 會傳回 WSAEINVAL， 而lBytesReturned 參數會指向零的 DWORD 值。

如果lpOverlapped為Null，則成功呼叫時所傳回之 lmicrosoftBytesReturned參數所指向的DWORD值不能為零。

如果重迭通訊端的 lpOverlapped 參數不是 Null ，則會起始無法立即完成的作業，而且稍後會指出完成。傳回之lHTTPBytesReturned參數所指向的DWORD值可能是零，因為儲存的資料大小在重迭作業完成之前無法判斷。當作業完成時發出適當的完成方法訊號時，可以擷取最終完成狀態。

lpvOverlapped

WSAOVERLAPPED結構的指標。

如果沒有重迭屬性建立通訊端，則會忽略 lpOverlapped參數。

如果使用重迭屬性開啟 s ，且 lpOverlapped 參數不是 Null，則會以重迭的 (非同步) 作業來執行作業。在此情況下， lpOverlapped 參數必須指向有效的 WSAOVERLAPPED 結構。

對於重迭的作業， WSAIoctl 或 WSPIoctl 函式會立即傳回，並在作業完成時發出適當的完成方法訊號。否則，在作業完成或發生錯誤之前，函式不會傳回。

lpCompletionRoutine

類型：_In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

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

lpThreadId

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

注意此參數僅適用于 WSPIoctl 函式。

lpErrno

錯誤碼的指標。

注意此參數僅適用于 WSPIoctl 函式。

傳回值

如果作業順利完成， WSAIoctl 或 WSPIoctl 函式會傳回零。

如果作業失敗或擱置中，WSAIoctl 或 WSPIoctl函式會傳回SOCKET_ERROR。若要取得擴充錯誤資訊，請呼叫 WSAGetLastError。

錯誤碼	意義
WSA_IO_PENDING	重迭的 I/O 作業正在進行中。如果成功起始重迭的作業，且稍後會指出完成，則會傳回此值。
WSA_OPERATION_ABORTED	由於執行緒結束或應用程式的要求，因此已經中止 I/O 作業。如果因為通訊端關閉或執行 SIO_FLUSH IOCTL 命令而取消重迭的作業，就會傳回此錯誤。
WSAEACCES	嘗試透過其存取權限禁止的方式來存取通訊端。此錯誤會在持續埠保留的數個情況下傳回，包括下列專案：使用者缺少本機電腦上的必要系統管理許可權，或應用程式未在增強的殼層中執行，因為內建系統管理員 (`RunAs administrator`) 。
WSAEFAULT	系統在嘗試在呼叫中使用指標引數時偵測到不正確指標位址。這個錯誤會傳回lpvInBuffer、lpvoutBuffer、lBytesReturned、lpOverlapped或lpCompletionRoutine參數，完全不包含在使用者位址空間的有效部分。
WSAEINPROGRESS	正在執行封鎖作業。如果在進行回呼時叫用函式，就會傳回此錯誤。
WSAEINTR	封鎖作業因呼叫 WSACancelBlockingCall而中斷。如果封鎖作業中斷，就會傳回此錯誤。
WSAEINVAL	提供的引數無效。如果 dwIoControlCode 參數不是有效的命令，或無法接受指定的輸入參數，或命令不適用於指定的通訊端類型，就會傳回此錯誤。
WSAENETDOWN	通訊端作業遇到停止的網路。如果網路子系統失敗，就會傳回此錯誤。
WSAENOTSOCK	嘗試在不是通訊端的某個專案上執行作業。如果描述元 s 不是通訊端，就會傳回此錯誤。
WSAEOPNOTSUPP	參考的物件類型不支援嘗試的作業。如果不支援指定的 IOCTL 命令，就會傳回此錯誤。如果傳輸提供者不支援 SIO_ASSOCIATE_PORT_RESER加值稅ION IOCTL，也會傳回此錯誤。在 UDP 或 TCP 以外的通訊端上嘗試使用 SIO_ASSOCIATE_PORT_RESER加值稅ION IOCTL 時，也會傳回此錯誤。

備註

Windows Vista 和更新版本的作業系統支援 SIO_ASSOCIATE_PORT_RESER加值稅ION IOCTL。

需要保留埠的應用程式和服務分為兩個類別。第一個類別包含需要特定埠作為作業一部分的元件。這類元件通常會偏好在應用程式資訊清單中指定其安裝時間 (所需的埠，例如) 。第二個類別包含需要在執行時間使用任何可用埠或埠區塊的元件。這兩個類別對應至特定和萬用字元埠保留要求。特定保留要求可能是持續性或執行時間，而萬用字元埠保留要求只有在執行時間才支援。

SIO_ASSOCIATE_PORT_RESER加值稅ION IOCTL 可用來建立 TCP 或 UDP 埠保留與持續性或執行時間保留的關聯。

CreatePersistentTcpPortReservation或CreatePersistentUdpPortReservation函式可讓您讓應用程式或服務保留 TCP 或 UDP 埠的持續性區塊。永續性埠保留會記錄在 Windows 中 TCP 或 UDP 模組的永續性存放區中。請注意，每次重新開機系統時，給定永續性埠保留的權杖可能會變更。

取得持續性 TCP 或 UDP 埠保留之後，應用程式就可以透過開啟 TCP 或 UDP 通訊端，從埠保留要求埠指派，然後呼叫 WSAIoctl 函式，指定 SIO_ASSOCIATE_PORT_RESER加值稅ION IOCTL，並在對通訊端上的系結函式發出呼叫之前傳遞保留權杖。

SIO_ACQUIRE_PORT_RESER加值稅ION IOCTL 可用來要求 TCP 或 UDP 埠區塊的執行時間保留。針對執行時間埠保留，埠集區會要求從授與保留通訊端的進程取用保留。只有在呼叫 SIO_ACQUIRE_PORT_RESER加值稅ION IOCTL 的通訊端存留期之後，執行時間埠保留才會持續。相反地，使用 CreatePersistentTcpPortReservation 或 CreatePersistentUdpPortReservation 函式建立的持續性埠保留，可能會由任何能夠取得持續性保留的程式取用。

取得執行時間 TCP 或 UDP 埠保留之後，應用程式就可以透過開啟 TCP 或 UDP 通訊端，從埠保留要求埠指派，然後呼叫 WSAIoctl 函式，以指定 SIO_ASSOCIATE_PORT_RESER加值稅ION IOCTL，並在對通訊端上的系結函式發出呼叫之前傳遞保留權杖。

如果 lpOverlapped 和 lpCompletionRoutine 參數都是 Null，則此函式中的通訊端將會被視為非重迭的通訊端。對於非重迭的通訊端， 會忽略 lpOverlapped 和 lpCompletionRoutine 參數，不同之處在于，如果通訊端處於封鎖模式，函式可以封鎖。如果 通訊端處於 非封鎖模式，此函式仍會封鎖，因為這個特定的 IOCTL 不支援非封鎖模式。

對於重迭的通訊端，無法立即完成的作業將會起始，而且稍後會指出完成。

根據服務提供者的實作而定，任何 IOCTL 可能會無限期地封鎖。如果應用程式無法容忍 WSAIoctl 或 WSPIoctl 函式呼叫中的封鎖，則特別可能封鎖的 IOCTL 建議重迭的 I/O。

SIO_ASSOCIATE_PORT_RESER加值稅ION IOCTL 在下列情況下，WSAEINTR或WSA_OPERATION_ABORTED可能會失敗：

I/O 管理員會取消要求。
通訊端已關閉。

傳遞至WSAIoctl或WSPIoctl函式的IOCTL SIO_ASSOCIATE_PORT_RESER加值稅ION，只有在使用者以 Administrators 群組的成員身分登入時，才能在應用程式中使用。如果使用者不是 Administrators 群組的成員時，會在應用程式中使用 SIO_ASSOCIATE_PORT_RESER加值稅ION IOCTL，則函式呼叫將會失敗，並傳回 WSAEACCES 。使用 SIO_ASSOCIATE_PORT_RESER加值稅ION IOCTL 也可能會失敗，因為 Windows Vista 和更新版本上的使用者帳戶控制 (UAC) 。如果使用者以系統管理員以外的系統管理員群組成員身分登入，否則此呼叫將會失敗，除非應用程式已在資訊清單檔中標示 requestedExecutionLevel 設定為 requireAdministrator，否則此呼叫將會失敗。如果應用程式缺少此資訊清單檔，則以系統管理員以外的 Administrators 群組成員身分登入的使用者，必須在增強的殼層中執行應用程式，因為內建系統管理員 (RunAs administrator) ，此函式才能成功。