listen 函式 (winsock2.h)

  • 發行項

接聽函式會將套接字置於接聽連入連線的狀態。

語法

int WSAAPI listen(
  [in] SOCKET s,
  [in] int    backlog
);

參數

[in] s

描述項，識別系結、未連線的套接字。

[in] backlog

擱置連線佇列的最大長度。 如果設定為 SOMAXCONN， 負責套接字的基礎 服務提供者會將待辦專案設定為合理的最大值。 如果設定為 SOMAXCONN_HINT (N) (其中 N 是數位) ，待辦專案值會調整為 N，調整為在 200、65535) (的範圍內。 請注意， SOMAXCONN_HINT 可用來將待辦項目設定為大於SOMAXCONN的可能值。

只有 Microsoft TCP/IP 服務提供者才支援SOMAXCONN_HINT。 沒有標準布建可取得實際待辦專案值。

傳回值

如果沒有發生錯誤， 接聽 會傳回零。 否則，會傳回 SOCKET_ERROR 的值，並呼叫 WSAGetLastError 來擷取特定的錯誤碼。

錯誤碼 意義
WSANOTINITIALISED
 使用這個函式之前，必須先進行成功的 WSAStartup 呼叫。
WSAENETDOWN
 網路子系統失敗。
WSAEADDRINUSE
 套接字的本機位址已在使用中，且套接字未標示為允許與SO_REUSEADDR重複使用位址。 這個錯誤通常會在執行 系結 函式期間發生，但如果系 結 至部分通配符位址， (涉及ADDR_ANY) ，而且需要在此函式時認可特定位址，則可能會延遲到此函式為止。
WSAEINPROGRESS
 封鎖的 Windows Sockets 1.1 呼叫正在進行中，或服務提供者仍在處理回呼函式。
WSAEINVAL
 套接字尚未與 系結系結。
WSAEISCONN
 套接字已連接。
WSAEMFILE
 不再有可用的通訊端描述項。
WSAENOBUFS
 沒有可用的緩衝區空間。
WSAENOTSOCK
 描述項不是套接字。
WSAEOPNOTSUPP
 參考的套接字不是支援 接聽 作業的類型。

備註

若要接受連線，會先使用套接字函式建立 套接字 ，並使用 bind 函式系結至本機位址。 傳入連線的待處理專案是透過 接聽來指定，然後使用 accept 函式接受連接。 例如，連接導向的套接字 ，SOCK_STREAM類型的 套接字會與 接聽搭配使用。 套接字會進入被動模式，讓進程認可傳入連線要求並排入佇列等候接受。

SOMAXCONN待處理專案的值是特殊的常數，指示負責套接字的基礎服務提供者將擱置連線佇列的長度設定為合理的最大值。

在 Windows Sockets 2 上，這個最大值預設為大型值， (通常是數百個以上的) 。

在藍牙應用程式中呼叫 接聽 函式時，強烈建議將較低的值用於 待 辦項目參數 (通常是 2 到 4) ，因為只接受少數客戶端連線。 這會減少配置供接聽套接字使用的系統資源。 這項相同的建議適用於預期只有少數用戶端連線的其他網路應用程式。

接 聽 函式通常是由一次可以有多個連線要求的伺服器使用。 如果連線要求送達且佇列已滿，用戶端會收到錯誤，並指出 WSAECONNREFUSED。

如果沒有可用的套接字描述元， 接聽 會嘗試繼續運作。 如果描述項變成可用，稍後接 聽 或 接受 的呼叫會將佇列重新填入至針對 待 辦項目參數指定的目前或最近值，可能的話，並繼續接聽連入連線。

如果在已經接聽的套接字上呼叫 接聽 函式，它會傳回成功，而不會變更 待 辦項目參數的值。 在接聽套接字上接聽的後續呼叫中，將待辦項目參數設定為 0，不會被視為適當的重設，特別是在套接字上有連線時。

注意 發出封鎖的 Winsock 呼叫，例如 接聽時，Winsock 可能需要等候網路事件，才能完成呼叫。 在此情況下，Winsock 會執行可警示的等候，而異步過程調用 (APC) 排程在相同線程上可能會中斷。 在 APC 內發出另一個封鎖 Winsock 呼叫，中斷相同線程上持續封鎖 Winsock 呼叫會導致未定義的行為，而且永遠不會由 Winsock 客戶端嘗試。
 

範例程序代碼

下列範例示範如何使用 接聽 函式。 
#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")

int wmain()
{

    //----------------------
    // Initialize Winsock
    WSADATA wsaData;
    int iResult = 0;

    SOCKET ListenSocket = INVALID_SOCKET;
    sockaddr_in service;

    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"WSAStartup() failed with error: %d\n", iResult);
        return 1;
    }
    //----------------------
    // Create a SOCKET for listening for incoming connection requests.
    ListenSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (ListenSocket == INVALID_SOCKET) {
        wprintf(L"socket function failed with error: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //----------------------
    // The sockaddr_in structure specifies the address family,
    // IP address, and port for the socket that is being bound.
    service.sin_family = AF_INET;
    service.sin_addr.s_addr = inet_addr("127.0.0.1");
    service.sin_port = htons(27015);

    iResult = bind(ListenSocket, (SOCKADDR *) & service, sizeof (service));
    if (iResult == SOCKET_ERROR) {
        wprintf(L"bind function failed with error %d\n", WSAGetLastError());
        iResult = closesocket(ListenSocket);
        if (iResult == SOCKET_ERROR)
            wprintf(L"closesocket function failed with error %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //----------------------
    // Listen for incoming connection requests 
    // on the created socket
    if (listen(ListenSocket, SOMAXCONN) == SOCKET_ERROR)
        wprintf(L"listen function failed with error: %d\n", WSAGetLastError());

    wprintf(L"Listening on socket...\n");

    iResult = closesocket(ListenSocket);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"closesocket function failed with error %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    WSACleanup();
    return 0;
}

範例程序代碼

如需使用接聽函式的另一個範例，請參閱 使用者入門With Winsock。

IrDA 套接字注意事項

  • 必須明確包含 Af_irda.h 頭檔。

相容性

待辦項目參數 (以無訊息方式) 基礎服務提供者所決定的合理值。 不合法的值會取代為最接近的法務值。 沒有標準布建可找出實際的待辦專案值。

Windows Phone 8：Windows Phone 8 和更新版本上的 Windows Phone Store 應用程式支援此函式。

Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更新版本上的 Windows 市集應用程式支援此函式。

規格需求

需求 值
最低支援的用戶端 Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 winsock2.h
程式庫 Ws2_32.lib
Dll Ws2_32.dll

另請參閱

Winsock 函式

Winsock 參考

接受

connect

socket