Win32 API 日本語リファレンス
ホーム › NetworkManagement.Snmp › SnmpStrToEntity

SnmpStrToEntity

関数
エンティティ名文字列からWinSNMPエンティティを生成する。
DLLwsnmp32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// wsnmp32.dll
#include <windows.h>

INT_PTR SnmpStrToEntity(
    INT_PTR session,
    LPCSTR string
);

パラメーター

名前型方向説明
sessionINT_PTRinWinSNMP セッションへのハンドル。
stringLPCSTRin

対象となる SNMP 管理エンティティを識別する、null で終わる文字列へのポインター。エンティティおよびコンテキストの変換モードの現在の設定によって、 SnmpStrToEntity が入力文字列を解釈する方法が次のように決まります。

エンティティ/コンテキストの変換モード 意味
SNMPAPI_TRANSLATED
実装は string パラメーターをわかりやすい名前として解釈します。実装は、自身のデータベースを使用して、その名前を SNMPv1 または SNMPv2C の構成要素に変換します。
SNMPAPI_UNTRANSLATED_V1
実装は string パラメーターをリテラルの SNMP トランスポート アドレスとして解釈します。
SNMPAPI_UNTRANSLATED_V2
実装は string パラメーターをリテラルの SNMP トランスポート アドレスとして解釈します。

戻り値の型: INT_PTR

公式ドキュメント

WinSNMP の SnmpStrToEntity 関数は、Microsoft WinSNMP 実装に固有の SNMP 管理エンティティに関する情報へのハンドルを返します。

戻り値

関数が成功した場合、戻り値は対象となる SNMP 管理エンティティへのハンドルです。

関数が失敗した場合、戻り値は SNMPAPI_FAILURE です。拡張エラー情報を取得するには、 SnmpGetLastError を呼び出します。 SnmpGetLastError 関数は、次のいずれかのエラーを返すことがあります。

リターン コード 説明
SNMPAPI_NOT_INITIALIZED
SnmpStartup 関数が正常に完了しませんでした。
SNMPAPI_ALLOC_ERROR
メモリの割り当て中にエラーが発生しました。
SNMPAPI_SESSION_INVALID
session パラメーターが無効です。
SNMPAPI_ENTITY_UNKNOWN
エンティティ文字列が無効です。
SNMPAPI_OTHER_ERROR
不明なエラー、または未定義のエラーが発生しました。

解説(Remarks)

エンティティおよびコンテキストの変換モードの現在の設定によって、 SnmpStrToEntity が、対象の管理エンティティを識別する入力文字列を解釈する方法が決まります。詳細については、 Support for IPX Address Strings in WinSNMP および Setting the Entity and Context Translation Mode を参照してください。

WinSNMP アプリケーションは、 SnmpStrToEntity 関数によって割り当てられたエンティティ ハンドルを解放するために、 SnmpFreeEntity 関数を呼び出す必要があります。詳細については、 WinSNMP Data Management Concepts を参照してください。

SnmpStrToEntity 関数は、WinSNMP アプリケーションが複数の WinSNMP 関数で srcEntity パラメーターまたは dstEntity パラメーターとして使用できる、有効なエンティティ ハンドルを返します。これらの関数には、 SnmpSendMsg、 SnmpRecvMsg、 SnmpRegister、 SnmpEncodeMsg、 SnmpDecodeMsg の各関数が含まれます。

実装は、現在のエンティティおよびコンテキストの変換モードを SnmpStartup 関数の nTranslateMode パラメーターで返します。WinSNMP アプリケーションは、 SnmpSetTranslateMode 関数を呼び出すことで、エンティティおよびコンテキストの変換モードの設定を変更できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// wsnmp32.dll
#include <windows.h>

INT_PTR SnmpStrToEntity(
    INT_PTR session,
    LPCSTR string
);
[DllImport("wsnmp32.dll", ExactSpelling = true)]
static extern IntPtr SnmpStrToEntity(
    IntPtr session,   // INT_PTR
    [MarshalAs(UnmanagedType.LPStr)] string string   // LPCSTR
);
<DllImport("wsnmp32.dll", ExactSpelling:=True)>
Public Shared Function SnmpStrToEntity(
    session As IntPtr,   ' INT_PTR
    <MarshalAs(UnmanagedType.LPStr)> [string] As String   ' LPCSTR
) As IntPtr
End Function
' session : INT_PTR
' string : LPCSTR
Declare PtrSafe Function SnmpStrToEntity Lib "wsnmp32" ( _
    ByVal session As LongPtr, _
    ByVal string As String) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

SnmpStrToEntity = ctypes.windll.wsnmp32.SnmpStrToEntity
SnmpStrToEntity.restype = ctypes.c_ssize_t
SnmpStrToEntity.argtypes = [
    ctypes.c_ssize_t,  # session : INT_PTR
    wintypes.LPCSTR,  # string : LPCSTR
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('wsnmp32.dll')
SnmpStrToEntity = Fiddle::Function.new(
  lib['SnmpStrToEntity'],
  [
    Fiddle::TYPE_INTPTR_T,  # session : INT_PTR
    Fiddle::TYPE_VOIDP,  # string : LPCSTR
  ],
  Fiddle::TYPE_INTPTR_T)
#[link(name = "wsnmp32")]
extern "system" {
    fn SnmpStrToEntity(
        session: isize,  // INT_PTR
        string: *const u8  // LPCSTR
    ) -> isize;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("wsnmp32.dll")]
public static extern IntPtr SnmpStrToEntity(IntPtr session, [MarshalAs(UnmanagedType.LPStr)] string string);
"@
$api = Add-Type -MemberDefinition $sig -Name 'wsnmp32_SnmpStrToEntity' -Namespace Win32 -PassThru
# $api::SnmpStrToEntity(session, string)
#uselib "wsnmp32.dll"
#func global SnmpStrToEntity "SnmpStrToEntity" sptr, sptr
; SnmpStrToEntity session, string   ; 戻り値は stat
; session : INT_PTR -> "sptr"
; string : LPCSTR -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "wsnmp32.dll"
#cfunc global SnmpStrToEntity "SnmpStrToEntity" sptr, str
; res = SnmpStrToEntity(session, string)
; session : INT_PTR -> "sptr"
; string : LPCSTR -> "str"
; INT_PTR SnmpStrToEntity(INT_PTR session, LPCSTR string)
#uselib "wsnmp32.dll"
#cfunc global SnmpStrToEntity "SnmpStrToEntity" intptr, str
; res = SnmpStrToEntity(session, string)
; session : INT_PTR -> "intptr"
; string : LPCSTR -> "str"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	wsnmp32 = windows.NewLazySystemDLL("wsnmp32.dll")
	procSnmpStrToEntity = wsnmp32.NewProc("SnmpStrToEntity")
)

// session (INT_PTR), string (LPCSTR)
r1, _, err := procSnmpStrToEntity.Call(
	uintptr(session),
	uintptr(unsafe.Pointer(windows.BytePtrFromString(string))),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // INT_PTR
function SnmpStrToEntity(
  session: NativeInt;   // INT_PTR
  string: PAnsiChar   // LPCSTR
): NativeInt; stdcall;
  external 'wsnmp32.dll' name 'SnmpStrToEntity';
result := DllCall("wsnmp32\SnmpStrToEntity"
    , "Ptr", session   ; INT_PTR
    , "AStr", string   ; LPCSTR
    , "Ptr")   ; return: INT_PTR
●SnmpStrToEntity(session, string) = DLL("wsnmp32.dll", "int SnmpStrToEntity(int, char*)")
# 呼び出し: SnmpStrToEntity(session, string)
# session : INT_PTR -> "int"
# string : LPCSTR -> "char*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "wsnmp32" fn SnmpStrToEntity(
    session: isize, // INT_PTR
    string: [*c]const u8 // LPCSTR
) callconv(std.os.windows.WINAPI) isize;
proc SnmpStrToEntity(
    session: int,  # INT_PTR
    string: cstring  # LPCSTR
): int {.importc: "SnmpStrToEntity", stdcall, dynlib: "wsnmp32.dll".}
pragma(lib, "wsnmp32");
extern(Windows)
ptrdiff_t SnmpStrToEntity(
    ptrdiff_t session,   // INT_PTR
    const(char)* string   // LPCSTR
);
ccall((:SnmpStrToEntity, "wsnmp32.dll"), stdcall, Int,
      (Int, Cstring),
      session, string)
# session : INT_PTR -> Int
# string : LPCSTR -> Cstring
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
intptr_t SnmpStrToEntity(
    intptr_t session,
    const char* string);
]]
local wsnmp32 = ffi.load("wsnmp32")
-- wsnmp32.SnmpStrToEntity(session, string)
-- session : INT_PTR
-- string : LPCSTR
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('wsnmp32.dll');
const SnmpStrToEntity = lib.func('__stdcall', 'SnmpStrToEntity', 'intptr_t', ['intptr_t', 'str']);
// SnmpStrToEntity(session, string)
// session : INT_PTR -> 'intptr_t'
// string : LPCSTR -> 'str'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("wsnmp32.dll", {
  SnmpStrToEntity: { parameters: ["isize", "buffer"], result: "isize" },
});
// lib.symbols.SnmpStrToEntity(session, string)
// session : INT_PTR -> "isize"
// string : LPCSTR -> "buffer"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
intptr_t SnmpStrToEntity(
    intptr_t session,
    const char* string);
C, "wsnmp32.dll");
// $ffi->SnmpStrToEntity(session, string);
// session : INT_PTR
// string : LPCSTR
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Wsnmp32 extends StdCallLibrary {
    Wsnmp32 INSTANCE = Native.load("wsnmp32", Wsnmp32.class);
    long SnmpStrToEntity(
        long session,   // INT_PTR
        String string   // LPCSTR
    );
}
@[Link("wsnmp32")]
lib Libwsnmp32
  fun SnmpStrToEntity = SnmpStrToEntity(
    session : LibC::SSizeT,   # INT_PTR
    string : UInt8*   # LPCSTR
  ) : LibC::SSizeT
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef SnmpStrToEntityNative = IntPtr Function(IntPtr, Pointer<Utf8>);
typedef SnmpStrToEntityDart = int Function(int, Pointer<Utf8>);
final SnmpStrToEntity = DynamicLibrary.open('wsnmp32.dll')
    .lookupFunction<SnmpStrToEntityNative, SnmpStrToEntityDart>('SnmpStrToEntity');
// session : INT_PTR -> IntPtr
// string : LPCSTR -> Pointer<Utf8>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function SnmpStrToEntity(
  session: NativeInt;   // INT_PTR
  string: PAnsiChar   // LPCSTR
): NativeInt; stdcall;
  external 'wsnmp32.dll' name 'SnmpStrToEntity';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "SnmpStrToEntity"
  c_SnmpStrToEntity :: CIntPtr -> CString -> IO CIntPtr
-- session : INT_PTR -> CIntPtr
-- string : LPCSTR -> CString
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let snmpstrtoentity =
  foreign "SnmpStrToEntity"
    (intptr_t @-> string @-> returning intptr_t)
(* session : INT_PTR -> intptr_t *)
(* string : LPCSTR -> string *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library wsnmp32 (t "wsnmp32.dll"))
(cffi:use-foreign-library wsnmp32)

(cffi:defcfun ("SnmpStrToEntity" snmp-str-to-entity :convention :stdcall) :int64
  (session :int64)   ; INT_PTR
  (string :string))   ; LPCSTR
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $SnmpStrToEntity = Win32::API::More->new('wsnmp32',
    'LPARAM SnmpStrToEntity(LPARAM session, LPCSTR string)');
# my $ret = $SnmpStrToEntity->Call($session, $string);
# session : INT_PTR -> LPARAM
# string : LPCSTR -> LPCSTR
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

公式の関連項目