WSAAsyncGetServByName 関数 (winsock2.h)

  • [アーティクル]

WSAAsyncGetServByName 関数は、サービス名とポートに対応するサービス情報を非同期的に取得します。

構文

HANDLE WSAAPI WSAAsyncGetServByName(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  const char *name,
  [in]  const char *proto,
  [out] char       *buf,
  [in]  int        buflen
);

パラメーター

[in] hWnd

非同期要求が完了したときにメッセージを受信するウィンドウのハンドル。

[in] wMsg

非同期要求が完了したときに受信するメッセージ。

[in] name

null で終わるサービス名へのポインター。

[in] proto

プロトコル名へのポインター。 NULL を指定できます。この場合、WSAAsyncGetServByName は、s_nameまたはいずれかのs_aliasesが指定された名前と一致する最初のサービス エントリを検索します。 それ以外の場合、WSAAsyncGetServByName は名前と proto の両方に一致します。

[out] buf

サービスデータを受け取るデータ領域へのポインター。 データ領域は、サーバー構造と、サービス側構造体のメンバーによって参照されるすべてのデータを格納するために Windows ソケットによって使用されるため、データ領域は、サーバー構造のサイズよりも大きくする必要があります。 MAXGETHOSTSTRUCT バイトのバッファーをお勧めします。

[in] buflen

buf パラメーターのデータ領域のサイズ (バイト単位)。

戻り値

戻り値は、非同期操作が正常に開始されたかどうかを指定します。 これは、操作自体の成功または失敗を意味するものではありません。

エラーが発生しない場合、 WSAAsyncGetServByName は、要求の非同期タスク ハンドルである HANDLE 型の 0 以外の値を返します (Windows HTASK と混同しないでください)。 この値は、2 つの方法で使用できます。 WSACancelAsyncRequest を使用して操作を取り消すために使用することも、wParam メッセージ パラメーターを調べることで非同期操作と完了メッセージを照合するために使用することもできます。

非同期操作を開始できなかった場合、 WSAAsyncServByName は 0 の値を返し、 WSAGetLastError を呼び出すことで特定のエラー番号を取得できます。

次のエラー コードは、アプリケーション ウィンドウがメッセージを受信したときに設定できます。 前述のように、WSAGETASYNCERROR マクロを使用して、応答メッセージ内の lParam から抽出できます。

エラー コード 意味
WSAENETDOWN
 ネットワーク サブシステムが失敗しました。
WSAENOBUFS
 バッファー領域が不足しています。
WSAEFAULT
 buf パラメーターがプロセス・アドレス・スペースの有効な部分にありません。
WSAHOST_NOT_FOUND
 権限のある応答ホストが見つかりません。
WSATRY_AGAIN
 認証されていないサービスが見つからないか、サーバーエラーです。
WSANO_RECOVERY
 回復不可能なエラー。サービス データベースにアクセスできません。
WSANO_DATA
 有効な名前。要求された型のデータ レコードはありません。
 

関数呼び出し時に次のエラーが発生する可能性があり、非同期操作を開始できなかったことを示します。

エラー コード 意味
WSANOTINITIALISED この関数を使用する前に、 WSAStartup 呼び出しが正常に行われる必要があります。
WSAENETDOWN ネットワーク サブシステムが失敗しました。
WSAEINPROGRESS ブロックしている Windows Sockets 1.1 呼び出しが進行中であるか、サービス プロバイダーがコールバック関数を処理しています。
WSAEWOULDBLOCK 現時点では、Windows ソケット実装内のリソースまたはその他の制約のため、非同期操作をスケジュールできません。

注釈

WSAAsyncGetServByName 関数は、getservbyname の非同期バージョンであり、サービス名に対応するサービス情報を取得するために使用されます。 Windows ソケットは操作を開始し、呼び出し元にすぐに戻り、アプリケーションが操作を識別するために使用できる不透明な非同期タスク ハンドルを返します。 操作が完了すると、結果 (存在する場合) が呼び出し元によって提供されるバッファーにコピーされ、メッセージがアプリケーションのウィンドウに送信されます。

非同期操作が完了すると、 hWnd パラメーターによって示されるアプリケーション ウィンドウは 、wMsg パラメーターでメッセージを受信します。 wParam パラメーターには、元の関数呼び出しによって返される非同期タスク ハンドルが含まれています。 lParam の上位 16 ビットには、エラー コードが含まれています。 エラー コードには、Winsock2.h で定義されている任意のエラーを指定できます。 エラー コード 0 は、非同期操作が正常に完了したことを示します。

正常に完了すると、元の関数呼び出しに指定されたバッファーには 、servent 構造体が含まれます。 この構造体のメンバーにアクセスするには、元のバッファー アドレスを servent 構造体ポインターにキャストし、必要に応じてアクセスする必要があります。

エラー コードが WSAENOBUFS の場合、元の呼び出しで buflen によって指定されたバッファーのサイズが小さすぎて、結果のすべての情報が格納されませんでした。 この場合、 lParam の下位 16 ビットには、必要なすべての情報を提供するために必要なバッファーのサイズが含まれます。 部分データが不十分であるとアプリケーションが判断した場合、 WSAAsyncGetServByName 関数呼び出しを、必要なすべての情報を受け取るのに十分な大きさのバッファーを使用して再発行できます (つまり、 lParam の 16 ビット未満)。

この関数に指定されたバッファーは、同じ servent 構造体のメンバーによって参照されるデータ領域の内容と共に、サービス構造を構築するために Windows Sockets によって使用されます。 WSAENOBUFS エラーを回避するには、アプリケーションで少なくとも MAXGETHOSTSTRUCT バイトのバッファーを指定する必要があります (Winsock2.h で定義されています)。

エラー コードとバッファー長は、Winsock2.h で次のように定義されているマクロ WSAGETASYNCERROR と WSAGETASYNCBUFLEN を使用して lParam から抽出する必要があります。

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

これらのマクロを使用すると、アプリケーションのソース コードの移植性が最大化されます。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winsock2.h (Winsock2.h を含む)
Library Ws2_32.lib
[DLL] Ws2_32.dll

こちらもご覧ください

WSACancelAsyncRequest

Winsock 関数

Winsock リファレンス

getservbyname