WSAAsyncGetServByName 関数 (winsock.h)

  • [アーティクル]

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

構文

HANDLE 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

サービス提供データを受信するデータ領域へのポインター。 データ領域は、サーバー構造と、servent 構造体のメンバーによって参照されるすべてのデータを格納するために Windows ソケットによって使用されるため、データ領域は、servent 構造体のサイズよりも大きくする必要があります。 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 ソケット 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 ソケットによって使用されます。 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
ヘッダー winsock.h (Winsock2.h を含む)
Library Ws2_32.lib
[DLL] Ws2_32.dll

こちらもご覧ください

WSACancelAsyncRequest

Winsock 関数

Winsock リファレンス

getservbyname