Share via

SnmpExtensionQueryEx 関数 (snmp.h)

  • [アーティクル]

[SNMP は、[要件] セクションで指定されたオペレーティング システムで使用できます。 今後のバージョンでは変更されるか、利用できなくなる場合もあります。 代わりに、WS-Man の Microsoft 実装である Windows リモート管理を使用します。

Microsoft SNMP サービスは SnmpExtensionQueryEx 関数を呼び出して、SNMP 拡張エージェントによって登録された 1 つ以上の MIB サブツリー内の変数を指定する SNMP 要求を処理します。 この関数は、SNMP 拡張エージェント API の要素です。

メモ SNMP バージョン 2C (SNMPv2C) データ型と多相 SNMP SET 操作をサポートする SnmpExtensionQueryEx 関数を使用することをお勧めします。 拡張エージェントが SnmpExtensionQueryEx 関数をエクスポートする場合、SNMP サービスは SnmpExtensionQuery 関数を 呼び出しません。
 

構文

BOOL SNMP_FUNC_TYPE SnmpExtensionQueryEx(
  [in]      UINT            nRequestType,
  [in]      UINT            nTransactionId,
  [in, out] SnmpVarBindList *pVarBindList,
  [in, out] AsnOctetString  *pContextInfo,
  [out]     AsnInteger32    *pErrorStatus,
  [out]     AsnInteger32    *pErrorIndex
);

パラメーター

[in] nRequestType

SNMP サービスが拡張エージェントに実行を要求する操作の種類を指定します。 このパラメーターには、次の値のいずれかを指定できます。

値 意味
SNMP_EXTENSION_GET
 指定した変数の値を取得します。
SNMP_EXTENSION_GET_NEXT
 指定した変数の辞書式後続の値または値を取得します。
SNMP_EXTENSION_SET_TEST
 指定した変数の値を検証します。 この操作により、COMMIT 要求中に書き込みが成功する確率が最大化されます。
SNMP_EXTENSION_SET_COMMIT
 指定した変数に新しい値を書き込みます。
SNMP_EXTENSION_SET_UNDO
 COMMIT 要求の前に、指定した変数の値をその値にリセットします。
SNMP_EXTENSION_SET_CLEANUP
 以前の要求と操作で割り当てられたリソースを解放します。
 

SET 要求の種類 、つまり、SNMP_EXTENSION_SET_で始まる要求の種類の詳細については、次の「解説」セクションを参照してください。

[in] nTransactionId

受信 SNMP 要求 PDU の一意識別子である DWORD 変数を指定します。 拡張エージェントはこの値を使用して、同じ PDU を含む SNMP サービスによる複数の呼び出しを関連付けることができます。

[in, out] pVarBindList

目的の変数を含む変数バインド リストへのポインター。

[in, out] pContextInfo

ユーザー定義のコンテキスト情報を含むオクテット文字列へのポインター。

拡張エージェントは、このパラメーターを使用して、マルチフェーズ SNMP SET 操作中に使用されるコンテキスト情報を格納できます。 拡張機能エージェントは、CLEANUP 要求中にこのパラメーターに関連付けられているリソースを解放する必要があります。 SNMP サービスは、このパラメーターに関連付けられているリソースを解放しません。 詳細については、次の「解説」セクションを参照してください。

[out] pErrorStatus

エラー状態の結果を受け取る変数へのポインター。 このパラメーターには、SNMPv2C で定義されている次のいずれかの値を指定できます。

エラー コード 意味
SNMP_ERRORSTATUS_NOERROR
 エージェントは、送信中にエラーが発生しなかったことを報告します。
SNMP_ERRORSTATUS_TOOBIG
 エージェントは、要求された SNMP 操作の結果を 1 つの SNMP メッセージに配置できませんでした。
SNMP_ERRORSTATUS_NOSUCHNAME
 要求された SNMP 操作によって、不明な変数が識別されました。
SNMP_ERRORSTATUS_BADVALUE
 要求された SNMP 操作で変数を変更しようとしましたが、構文エラーまたは値エラーが指定されました。
SNMP_ERRORSTATUS_READONLY
 要求された SNMP 操作は、変数のコミュニティ プロファイルに従って、変更が許可されていない変数を変更しようとしました。
SNMP_ERRORSTATUS_GENERR
 要求された SNMP 操作中に、ここに記載されているエラーの 1 つ以外のエラーが発生しました。
SNMP_ERRORSTATUS_NOACCESS
 指定された SNMP 変数にアクセスできません。
SNMP_ERRORSTATUS_WRONGTYPE
 値は、変数に必要な型と矛盾する型を指定します。
SNMP_ERRORSTATUS_WRONGLENGTH
 値は、変数に必要な長さと矛盾する長さを指定します。
SNMP_ERRORSTATUS_WRONGENCODING
 この値には、フィールドの ASN.1 タグと矛盾する抽象構文表記 1 (ASN.1) エンコードが含まれています。
SNMP_ERRORSTATUS_WRONGVALUE
 値を変数に割り当てることはできません。
SNMP_ERRORSTATUS_NOCREATION
 変数が存在せず、エージェントで作成できません。
SNMP_ERRORSTATUS_INCONSISTENTVALUE
 値は、他のマネージド オブジェクトの値と矛盾しています。
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE
 変数に値を割り当てるには、現在使用できないリソースの割り当てが必要です。
SNMP_ERRORSTATUS_COMMITFAILED
 検証エラーは発生しませんでしたが、変数は更新されませんでした。
SNMP_ERRORSTATUS_UNDOFAILED
 検証エラーは発生しませんでした。 割り当てを元に戻すことができなかったため、一部の変数が更新されました。
SNMP_ERRORSTATUS_AUTHORIZATIONERROR
 承認エラーが発生しました。
SNMP_ERRORSTATUS_NOTWRITABLE
 変数は存在しますが、エージェントはそれを変更できません。
SNMP_ERRORSTATUS_INCONSISTENTNAME
 変数が存在しません。名前付きオブジェクト インスタンスが他のマネージド オブジェクトの値と矛盾しているため、エージェントで作成できません。

[out] pErrorIndex

エラー インデックスの結果を受け取る変数へのポインター。

戻り値

関数が成功した場合、戻り値は TRUE になります。

関数が失敗した場合、戻り値は FALSE になります。

注釈

SNMP サービスは SnmpExtensionQueryEx 関数を複数回呼び出して、受信 SNMP SET 要求を処理します。 サービスは、TEST 要求フェーズ、COMMIT 要求フェーズ、UNDO 要求フェーズ、CLEANUP 要求フェーズの間に SnmpExtensionQueryEx を呼び出すことができます。

TEST 要求

SNMP サービスは、最初に dwRequestType が SNMP_EXTENSION_SET_TESTの SnmpExtensionQueryEx 関数を呼び出すことによって、SNMP SET 要求の種類を処理します。 サービスは、要求内の変数バインドを担当する各拡張機能エージェントを呼び出します。 各拡張エージェントは、変数バインド リスト内の変数を検証する必要があります。 必要に応じて、 pContextInfo パラメーターによって指される変数に、次の要求に必要なコンテキスト情報を格納できます。

TEST 要求が失敗した場合、サービスは CLEANUP 要求を開始します。 このサービスは、以前に TRUE を 返した各拡張機能エージェントを 、SnmpExtensionQueryEx 関数を使用して再度 TEST 要求に呼び出します。 サービスは、 SNMP_EXTENSION_SET_CLEANUP dwRequestType を使用して各拡張機能エージェントを呼び出します。

COMMIT 要求

すべての拡張エージェントが TEST 要求に TRUE を返す場合、SNMP サービスは、SNMP_EXTENSION_SET_COMMIT dwRequestType を使用して SnmpExtensionQueryEx 関数を使用して各拡張エージェントを呼び出します。 サービスは、拡張機能エージェントがサービスに渡した拡張エージェントコンテキスト情報に戻ります。 これは、TEST 要求中に pContextInfo パラメーターで渡された拡張エージェントのコンテキスト情報です。 拡張エージェントは、コンテキスト情報を使用して、インストルメンテーション固有の方法で指定された変数の値を更新できます。

拡張機能エージェントがロールバック処理をサポートしている場合、この時点で pContextInfo パラメーターのコンテキスト情報を更新できます。 SNMP サービスは、UNDO 要求中に拡張機能エージェントに情報を渡します。

すべての拡張機能エージェントが COMMIT 要求に TRUE を返す場合、サービスは、SNMP_EXTENSION_SET_CLEANUP dwRequestType を使用して SnmpExtensionQueryEx 関数を使用して各拡張機能エージェントを呼び出します。

拡張機能エージェントが COMMIT 要求に失敗した場合、サービスは CLEANUP 要求も開始します。 このサービスは、以前に TRUE を 返した各拡張機能エージェントを 、SnmpExtensionQueryEx 関数を使用して COMMIT 要求に再度呼び出します。 サービスは、 SNMP_EXTENSION_SET_CLEANUP dwRequestType を使用して各拡張機能エージェントを呼び出します。

CLEANUP 要求

サービスは、TEST または COMMIT 要求中に pContextInfo パラメーターで渡されたコンテキスト情報を拡張機能エージェントに返します。 拡張機能エージェントは、この時点で パラメーターに関連付けられているリソースを解放する必要があります。

UNDO 要求

拡張機能エージェントが COMMIT 要求に FALSE を 返した場合、SNMP サービスは COMMIT 要求を終了します。 このサービスは、 TRUE を 返した各拡張機能エージェントを、 dwRequestType が SNMP_EXTENSION_SET_UNDOの COMMIT 要求に呼び出します。 これにより、COMMIT 要求が失敗したことを拡張エージェントに通知し、ロールバック処理を開始する必要があります。

拡張エージェントは、COMMIT 要求が失敗する前の値に戻って、目的の変数の値のリセットを試みる必要があります。 これを行うには、拡張機能エージェントは COMMIT 要求中に pContextInfo パラメーターで返されるコンテキスト情報を使用します。

拡張エージェントが UNDO 要求に FALSE を 返した場合、SET 操作全体がエラー コード SNMP_ERRORSTATUS_UNDOFAILEDで失敗します。 すべての拡張エージェントが UNDO 要求に TRUE を 返した場合、SNMP SET 操作は、COMMIT 要求に失敗した拡張機能エージェントによって設定されたエラー コードで失敗します。

UNDO 要求の後、サービスは常に、SNMP_EXTENSION_SET_CLEANUP dwRequestType を使用して SnmpExtensionQueryEx 関数を使用して各拡張機能エージェントを呼び出します。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー snmp.h

こちらもご覧ください

AsnOctetString

SNMP 関数

簡易ネットワーク管理プロトコル (SNMP) の概要

SnmpExtensionQuery

SnmpVarBindList