SnmpExtensionQueryEx 함수(snmp.h)

아티클
08/26/2023

[SNMP는 요구 사항 섹션에 지정된 운영 체제에서 사용할 수 있습니다. 이후 버전에서는 변경되거나 제공되지 않을 수 있습니다. 대신 WS-Man의 Microsoft 구현인 Windows 원격 관리를 사용합니다.]

Microsoft SNMP 서비스는 SnmpExtensionQueryEx 함수를 호출하여 SNMP 확장 에이전트에 의해 등록된 하나 이상의 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

사용자 정의 컨텍스트 정보를 포함하는 octet 문자열에 대한 포인터입니다.

확장 에이전트는 이 매개 변수를 사용하여 다단계 SNMP SET 작업 중에 사용되는 컨텍스트 정보를 저장할 수 있습니다. 확장 에이전트는 CLEANUP 요청 중에 이 매개 변수와 연결된 리소스를 해제해야 합니다. SNMP 서비스는 이 매개 변수와 연결된 리소스를 해제하지 않습니다. 자세한 내용은 다음 설명 섹션을 참조하세요.

[out] pErrorStatus

오류 상태 결과를 수신할 변수에 대한 포인터입니다. 이 매개 변수는 SNMPv2C에서 정의한 다음 값 중 하나일 수 있습니다.

오류 코드	의미
SNMP_ERRORSTATUS_NOERROR	에이전트는 전송 중에 오류가 발생하지 않았다고 보고합니다.
SNMP_ERRORSTATUS_TOOBIG	에이전트가 요청된 SNMP 작업의 결과를 단일 SNMP 메시지에 배치할 수 없습니다.
SNMP_ERRORSTATUS_NOSUCHNAME	요청된 SNMP 작업에서 알 수 없는 변수를 식별했습니다.
SNMP_ERRORSTATUS_BADVALUE	요청된 SNMP 작업에서 변수를 변경하려고 했지만 구문 또는 값 오류를 지정했습니다.
SNMP_ERRORSTATUS_READONLY	요청된 SNMP 작업은 변수의 커뮤니티 프로필에 따라 변경할 수 없는 변수를 변경하려고 했습니다.
SNMP_ERRORSTATUS_GENERR	여기에 나열된 오류 중 하나 이외의 오류가 요청된 SNMP 작업 중에 발생했습니다.
SNMP_ERRORSTATUS_NOACCESS	지정된 SNMP 변수에 액세스할 수 없습니다.
SNMP_ERRORSTATUS_WRONGTYPE	값은 변수에 필요한 형식과 일치하지 않는 형식을 지정합니다.
SNMP_ERRORSTATUS_WRONGLENGTH	값은 변수에 필요한 길이와 일치하지 않는 길이를 지정합니다.
SNMP_ERRORSTATUS_WRONGENCODING	값에는 필드의 ASN.1 태그와 일치하지 않는 ASN.1(Abstract Syntax Notation One) 인코딩이 포함됩니다.
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	변수가 없습니다. 명명된 개체 instance 다른 관리되는 개체의 값과 일치하지 않으므로 에이전트가 에이전트를 만들 수 없습니다.

[out] pErrorIndex

오류 인덱스 결과를 받을 변수에 대한 포인터입니다.

반환 값

함수가 성공하면 반환 값은 TRUE입니다.

함수가 실패하면 반환 값은 FALSE입니다.

설명

SNMP 서비스는 SnmpExtensionQueryEx 함수를 여러 번 호출하여 들어오는 SNMP SET 요청을 처리합니다. 서비스는 TEST 요청 단계, COMMIT 요청 단계, UNDO 요청 단계 및 CLEANUP 요청 단계 중에 SnmpExtensionQueryEx 를 호출할 수 있습니다.

TEST 요청

SNMP 서비스는 먼저 SNMP_EXTENSION_SET_TEST dwRequestType을 사용하여 SnmpExtensionQueryEx 함수를 호출하여 SNMP SET 요청 형식을 처리합니다. 서비스는 요청의 변수 바인딩을 담당하는 각 확장 에이전트를 호출합니다. 각 확장 에이전트는 변수 바인딩 목록의 변수 유효성을 검사해야 합니다. 필요에 따라 pContextInfo 매개 변수가 가리키는 변수에 다음 요청에 필요한 컨텍스트 정보를 저장할 수 있습니다.

TEST 요청이 실패하면 서비스에서 CLEANUP 요청을 시작합니다. 서비스는 SnmpExtensionQueryEx 함수를 사용하여 이전에 TRUE를 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 요청도 시작합니다. 서비스는 SnmpExtensionQueryEx 함수를 사용하여 이전에 COMMIT 요청에 TRUE를 반환한 각 확장 에이전트를 다시 호출합니다. 서비스는 SNMP_EXTENSION_SET_CLEANUP dwRequestType을 사용하여 각 확장 에이전트를 호출합니다.

CLEANUP 요청

서비스는 TEST 또는 COMMIT 요청 중에 pContextInfo 매개 변수에 전달된 컨텍스트 정보를 확장 에이전트에 반환합니다. 확장 에이전트는 현재 매개 변수와 연결된 리소스를 해제해야 합니다.

UNDO 요청

확장 에이전트가 COMMIT 요청에 FALSE 를 반환하는 경우 SNMP 서비스는 COMMIT 요청을 종료합니다. 서비스는 dwRequestType의 SNMP_EXTENSION_SET_UNDO 사용하여 COMMIT 요청에 TRUE를 반환한 각 확장 에이전트를 호출합니다. 이렇게 하면 COMMIT 요청이 실패했음을 확장 에이전트에 알리고 롤백 처리를 시작해야 합니다.

확장 에이전트는 관심 있는 변수의 값을 COMMIT 요청이 실패하기 전의 값으로 다시 설정하려고 시도해야 합니다. 이를 위해 확장 에이전트는 COMMIT 요청 중에 pContextInfo 매개 변수에 반환된 컨텍스트 정보를 사용합니다.

확장 에이전트가 UNDO 요청에 FALSE 를 반환하면 오류 코드 SNMP_ERRORSTATUS_UNDOFAILED 전체 SET 작업이 실패합니다. 모든 확장 에이전트가 UNDO 요청에 TRUE 를 반환하면 COMMIT 요청에 실패한 확장 에이전트가 설정한 오류 코드로 인해 SNMP SET 작업이 실패합니다.

UNDO 요청 후 서비스는 항상 SNMP_EXTENSION_SET_CLEANUP dwRequestType을 사용하여 SnmpExtensionQueryEx 함수를 사용하여 각 확장 에이전트를 호출합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	snmp.h