From 6f7913a20db1f59a67cc22ae3b6ce6d4d013deee Mon Sep 17 00:00:00 2001 From: Micael Karlberg Date: Wed, 13 Apr 2011 12:05:20 +0200 Subject: Proper interface documentation for new API. Also release notes with links into API. --- lib/snmp/doc/src/notes.xml | 23 ++- lib/snmp/doc/src/snmpm.xml | 354 ++++++++++++++++++++++++++++----------------- 2 files changed, 247 insertions(+), 130 deletions(-) (limited to 'lib/snmp') diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml index f5fa7065fb..11d2a513df 100644 --- a/lib/snmp/doc/src/notes.xml +++ b/lib/snmp/doc/src/notes.xml @@ -53,9 +53,30 @@

Aux Id: Seq 11790

+ +

[manager] The API for snmp requests has been changed to + allow the caller to override some configuration.

+

See + sync_get/3,4, + async_get/3,4, + sync_get_next/3,4, + async_get_next/3,4, + sync_get_bulk/5,6, + async_get_bulk/5,6, + sync_set/3,4 and + async_set/3,4 + for more info.

+

Own Id: OTP-9162

+ +

[manager] The old API functions (for get and set - requests) are now officially deprecated. + requests: + snmpm:g/3,4,5,6,7, snmpm:ag/3,4,5,6,7, + snmpm:gn/3,4,5,6,7, snmpm:agn/3,4,5,6,7, + snmpm:s/3,4,5,6,7, snmpm:s/3,4,5,6,7, + snmpm:gb/5,6,7,8,9 and snmpm:agb/5,6,7,8,9) + are now officially deprecated. They will be removed as of R16B.

Own Id: OTP-9174

 diff --git a/lib/snmp/doc/src/snmpm.xml b/lib/snmp/doc/src/snmpm.xml index 1ee391d9ba..db7abd6867 100644 --- a/lib/snmp/doc/src/snmpm.xml +++ b/lib/snmp/doc/src/snmpm.xml @@ -1,4 +1,4 @@ - + @@ -63,6 +63,10 @@ value_type() = o ('OBJECT IDENTIFIER') | c64 ('Counter64') | tt ('TimeTicks') value() = term() +community() = string() +sec_model() = any | v1 | v2c | usm +sec_name() = string() +sec_level() = noAuthNoPriv | authNoPriv | authPriv ]]> @@ -488,22 +492,20 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 sync_get(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get(UserId, TargetName, ContextName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get(UserId, TargetName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get(UserId, TargetName, ContextName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get(UserId, TargetName, ContextName, Oids, Timeout, ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason} + sync_get(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason} Synchronous get-request UserId = term() TargetName = target_name() - ContextName = string() Oids = [oid()] - Timeout = integer() - ExtraInfo = term() + SendOpts = send_opts() + send_opts() = [send_opt()] + send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()} SnmpReply = snmp_reply() Remaining = integer() - Reason = {send_failed, ReqId, R} | {invalid_sec_info, SecInfo, SnmpInfo} | term() - R = term() + Reason = {send_failed, ReqId, ActualReason} | {invalid_sec_info, SecInfo, SnmpInfo} | term() + ReqId = term() + ActualReason = term() SecInfo = [sec_info()] sec_info() = {sec_tag(), ExpectedValue, ReceivedValue} sec_tag() = atom() @@ -512,19 +514,29 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1

Synchronous get-request.

-

Remaining is the remaining time of the given or - default timeout time.

+ +

Remaining is the remaining time of the given (or default) + timeout time.

+

When Reason is {send_failed, ...} it means that - the net_if process failed to send the message. This could happen - because of any number of reasons, i.e. encoding error. R - is the actual reason in this case.

-

ExtraInfo is an opaque data structure passed on to - the net-if process. The net-if process included in this - application makes no use of this info, so the only use for it - in such a configuration (when using the built in net-if) would - be tracing.

-

For SnmpInfo, see the user callback function - handle_report.

+ the net_if process failed to send the message. This could happen + because of any number of reasons, i.e. encoding error. + ActualReason is the actual reason in this case.

+ +

The send option extra specifies an opaque data structure + passed on to the net-if process. The net-if process included in this + application makes no use of this info, so the only use for it + in such a option (when using the built in net-if) would + be tracing.

+ +

Some of the send options (community, sec_model, + sec_name, sec_level and max_message_size) + are override options. That is, + for this request, they override any configuration done + when the agent was registered.

+ +

For SnmpInfo, see the user callback function + handle_report.

 @@ -532,33 +544,39 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 async_get(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason} - async_get(UserId, TargetName, ContextName, Oids) -> {ok, ReqId} | {error, Reason} - async_get(UserId, TargetName, Oids, Expire) -> {ok, ReqId} | {error, Reason} - async_get(UserId, TargetName, ContextName, Oids, Expire) -> {ok, ReqId} | {error, Reason} - async_get(UserId, TargetName, ContextName, Oids, Expire, ExtraInfo) -> {ok, ReqId} | {error, Reason} + async_get(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason} Asynchronous get-request UserId = term() TargetName = target_name() - ContextName = string() Oids = [oid()] - Expire = integer() - ExtraInfo = term() + SendOpts = send_opts() + send_opts() = [send_opt()] + send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()} ReqId = term() Reason = term()

Asynchronous get-request.

+

The reply, if it arrives, will be delivered to the user - through a call to the snmpm_user callback function - handle_pdu.

-

The Expire time indicates for how long the request is - valid (after which the manager is free to delete it).

-

ExtraInfo is an opaque data structure passed on to - the net-if process. The net-if process included in this - application makes no use of this info, so the only use for it - in such a configuration (when using the built in net-if) would - be tracing.

+ through a call to the snmpm_user callback function + handle_pdu.

+ +

The send option timeout specifies for how long the request is + valid (after which the manager is free to delete it).

+ +

The send option extra specifies an opaque data structure + passed on to the net-if process. The net-if process included in this + application makes no use of this info, so the only use for it + in such a configuration (when using the built in net-if) would + be tracing.

+ +

Some of the send options (community, sec_model, + sec_name, sec_level and max_message_size) + are override options. That is, + for this request, they override any configuration done + when the agent was registered.

@@ -566,35 +584,51 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 sync_get_next(UserId, TargetName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get_next(UserId, TargetName, ContextName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get_next(UserId, TargetName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get_next(UserId, TargetName, ContextName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get_next(UserId, TargetName, ContextName, Oids, Timeout, ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason} + sync_get_next(UserId, TargetName, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason} Synchronous get-next-request UserId = term() TargetName = target_name() - ContextName = string() Oids = [oid()] - Timeout = integer() - ExtraInfo = term() + SendOpts = send_opts() + send_opts() = [send_opt()] + send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()} SnmpReply = snmp_reply() Remaining = integer() - Reason = {send_failed, ReqId, R} | {invalid_sec_info, SecInfo, SnmpInfo} | term() - R = term() + Reason = {send_failed, ReqId, ActualReason} | {invalid_sec_info, SecInfo, SnmpInfo} | term() + ReqId = term() + ActualReason = term() + SecInfo = [sec_info()] + sec_info() = {sec_tag(), ExpectedValue, ReceivedValue} + sec_tag() = atom() + ExpectedValue = ReceivedValue = term() + SnmpInfo = term()

Synchronous get-next-request.

-

Remaining time of the given or default timeout time.

+ +

Remaining is the remaining time of the given (or default) + timeout time.

+

When Reason is {send_failed, ...} it means that - the net_if process failed to send the message. This could happen - because of any number of reasons, i.e. encoding error. R - is the actual reason in this case.

-

ExtraInfo is an opaque data structure passed on to - the net-if process. The net-if process included in this - application makes no use of this info, so the only use for it - in such a configuration (when using the built in net-if) would - be tracing.

+ the net_if process failed to send the message. This could happen + because of any number of reasons, i.e. encoding error. + ActualReason is the actual reason in this case.

+ +

The send option extra specifies an opaque data structure + passed on to the net-if process. The net-if process included in this + application makes no use of this info, so the only use for it + in such a configuration (when using the built in net-if) would + be tracing.

+ +

Some of the send options (community, sec_model, + sec_name, sec_level and max_message_size) + are override options. That is, + for this request, they override any configuration done + when the agent was registered.

+ +

For SnmpInfo, see the user callback function + handle_report.

 @@ -602,27 +636,36 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 async_get_next(UserId, TargetName, Oids) -> {ok, ReqId} | {error, Reason} - async_get_next(UserId, TargetName, ContextName, Oids) -> {ok, ReqId} | {error, Reason} - async_get_next(UserId, TargetName, Oids, Expire) -> {ok, ReqId} | {error, Reason} - async_get_next(UserId, TargetName, ContextName, Oids, Expire) -> {ok, ReqId} | {error, Reason} - async_get_next(UserId, TargetName, ContextName, Oids, Expire, ExtraInfo) -> {ok, ReqId} | {error, Reason} + async_get_next(UserId, TargetName, Oids, SendOpts) -> {ok, ReqId} | {error, Reason} Asynchronous get-next-request UserId = term() TargetName = target_name() - ContextName = string() Oids = [oid()] - Expire = integer() - ExtraInfo = term() + send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()} ReqId = integer() Reason = term()

Asynchronous get-next-request.

+

The reply will be delivered to the user through a call - to the snmpm_user callback function handle_pdu.

-

The Expire time indicates for how long the request is - valid (after which the manager is free to delete it).

+ to the snmpm_user callback function handle_pdu.

+ +

The send option timeout specifies for how long the request is + valid (after which the manager is free to delete it).

+ +

The send option extra specifies an opaque data structure + passed on to the net-if process. The net-if process included in this + application makes no use of this info, so the only use for it + in such a configuration (when using the built in net-if) would + be tracing.

+ +

Some of the send options (community, sec_model, + sec_name, sec_level and max_message_size) + are override options. That is, + for this request, they override any configuration done + when the agent was registered.

@@ -630,37 +673,54 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 sync_set(UserId, TargetName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_set(UserId, TargetName, ContextName, VarsAndVals) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_set(UserId, TargetName, VarsAndVals, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_set(UserId, TargetName, ContextName, VarsAndVals, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_set(UserId, TargetName, ContextName, VarsAndVals, Timeout, ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason} + sync_set(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason} Synchronous set-request UserId = term() TargetName = target_name() - ContextName = string() VarsAndVals = vars_and_vals() - Timeout = integer() - ExtraInfo = term() + SendOpts = send_opts() + send_opts() = [send_opt()] + send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()} SnmpReply = snmp_reply() Remaining = integer() Reason = {send_failed, ReqId, ActualReason} | {invalid_sec_info, SecInfo, SnmpInfo} | term() + ReqId = term() ActualReason = term() + SecInfo = [sec_info()] + sec_info() = {sec_tag(), ExpectedValue, ReceivedValue} + sec_tag() = atom() + ExpectedValue = ReceivedValue = term() + SnmpInfo = term()

Synchronous set-request.

-

Remaining time of the given or default timeout time.

-

When Reason is {send_failed, ...} it means that - the net_if process failed to send the message. This could happen - because of any number of reasons, i.e. encoding error. R - is the actual reason in this case.

-

When var_and_val() is {oid(), value()}, the - manager makes an educated guess based on the loaded mibs.

-

ExtraInfo is an opaque data structure passed on to - the net-if process. The net-if process included in this - application makes no use of this info, so the only use for it - in such a configuration (when using the built in net-if) would - be tracing.

+ +

Remaining is the remaining time of the given (or default) + timeout time.

+ +

When Reason is {send_failed, ...} it means that + the net_if process failed to send the message. This could happen + because of any number of reasons, i.e. encoding error. + ActualReason is the actual reason in this case.

+ +

When var_and_val() is {oid(), value()}, the + manager makes an educated guess based on the loaded mibs.

+ +

The send option extra specifies an opaque data structure + passed on to the net-if process. The net-if process included in this + application makes no use of this info, so the only use for it + in such a configuration (when using the built in net-if) would + be tracing.

+ +

Some of the send options (community, sec_model, + sec_name, sec_level and max_message_size) + are override options. That is, + for this request, they override any configuration done + when the agent was registered.

+ +

For SnmpInfo, see the user callback function + handle_report.

 @@ -668,33 +728,41 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 async_set(UserId, TargetName, VarsAndVals) -> {ok, ReqId} | {error, Reason} - async_set(UserId, TargetName, ContextName, VarsAndVals) -> {ok, ReqId} | {error, Reason} - async_set(UserId, TargetName, VarsAndVals, Expire) -> {ok, ReqId} | {error, Reason} - async_set(UserId, TargetName, ContextName, VarsAndVals, Expire) -> {ok, ReqId} | {error, Reason} - async_set(UserId, TargetName, ContextName, VarsAndVals, Expire, ExtraInfo) -> {ok, ReqId} | {error, Reason} + async_set(UserId, TargetName, VarsAndVals, SendOpts) -> {ok, ReqId} | {error, Reason} Asynchronous set-request UserId = term() TargetName = target_name() VarsAndVals = vars_and_vals() - Expire = integer() - ExtraInfo = term() + SendOpts = send_opts() + send_opts() = [send_opt()] + send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()} ReqId = term() Reason = term()

Asynchronous set-request.

-

The reply will be delivered to the user through a call - to the snmpm_user callback function handle_pdu.

-

The Expire time indicates for how long the request is - valid (after which the manager is free to delete it).

-

When var_and_val() is {oid(), value()}, the - manager makes an educated guess based on the loaded mibs.

-

ExtraInfo is an opaque data structure passed on to - the net-if process. The net-if process included in this - application makes no use of this info, so the only use for it - in such a configuration (when using the built in net-if) would - be tracing.

+ +

The reply will be delivered to the user through a call + to the snmpm_user callback function handle_pdu.

+ +

The send option timeout specifies for how long the request is + valid (after which the manager is free to delete it).

+ +

When var_and_val() is {oid(), value()}, the + manager makes an educated guess based on the loaded mibs.

+ +

The send option extra specifies an opaque data structure + passed on to the net-if process. The net-if process included in this + application makes no use of this info, so the only use for it + in such a configuration (when using the built in net-if) would + be tracing.

+ +

Some of the send options (community, sec_model, + sec_name, sec_level and max_message_size) + are override options. That is, + for this request, they override any configuration done + when the agent was registered.

@@ -702,36 +770,53 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids, Timeout) -> {ok, SnmpReply, Remaining} | {error, Reason} - sync_get_bulk(UserId, TragetName, NonRep, MaxRep, ContextName, Oids, Timeout, ExtraInfo) -> {ok, SnmpReply, Remaining} | {error, Reason} + sync_get_bulk(UserId, TragetName, NonRep, MaxRep, Oids, SendOpts) -> {ok, SnmpReply, Remaining} | {error, Reason} Synchronous get-bulk-request UserId = term() TargetName = target_name() NonRep = integer() MaxRep = integer() - ContextName = string() Oids = [oid()] - Timeout = integer() - ExtraInfo = term() + SendOpts = send_opts() + send_opts() = [send_opt()] + send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()} SnmpReply = snmp_reply() Remaining = integer() - Reason = {send_failed, ReqId, R} | {invalid_sec_info, SecInfo, SnmpInfo} | term() + Reason = {send_failed, ReqId, ActualReason} | {invalid_sec_info, SecInfo, SnmpInfo} | term() + ReqId = term() + ActualReason = term() + SecInfo = [sec_info()] + sec_info() = {sec_tag(), ExpectedValue, ReceivedValue} + sec_tag() = atom() + ExpectedValue = ReceivedValue = term() + SnmpInfo = term()

Synchronous get-bulk-request (See RFC1905).

-

Remaining time of the given or default timeout time.

+ +

Remaining is the remaining time of the given (or default) + timeout time.

+

When Reason is {send_failed, ...} it means that - the net_if process failed to send the message. This could happen - because of any number of reasons, i.e. encoding error. R - is the actual reason in this case.

-

ExtraInfo is an opaque data structure passed on to - the net-if process. The net-if process included in this - application makes no use of this info, so the only use for it - in such a configuration (when using the built in net-if) would - be tracing.

+ the net_if process failed to send the message. This could happen + because of any number of reasons, i.e. encoding error. + ActualReason is the actual reason in this case.

+ +

The send option extra specifies an opaque data structure + passed on to the net-if process. The net-if process included in this + application makes no use of this info, so the only use for it + in such a configuration (when using the built in net-if) would + be tracing.

+ +

Some of the send options (community, sec_model, + sec_name, sec_level and max_message_size) + are override options. That is, + for this request, they override any configuration done + when the agent was registered.

+ +

For SnmpInfo, see the user callback function + handle_report.

 @@ -739,29 +824,40 @@ priv_key = [integer()] (length is 16 if priv = usmDESPrivProtocol | usmAesCfb1 async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids) -> {ok, ReqId} | {error, Reason} - async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids) -> {ok, ReqId} | {error, Reason} - async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids, Expire) -> {ok, ReqId} | {error, Reason} - async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids, Expire) -> {ok, ReqId} | {error, Reason} - async_get_bulk(UserId, TargetName, NonRep, MaxRep, ContextName, Oids, Expire, ExtraInfo) -> {ok, ReqId} | {error, Reason} + async_get_bulk(UserId, TargetName, NonRep, MaxRep, Oids, SendOpts) -> {ok, ReqId} | {error, Reason} Asynchronous get-bulk-request UserId = term() TargetName = target_name() NonRep = integer() MaxRep = integer() - ContextName = string() Oids = [oid()] - Expire = integer() - ExtraInfo = term() + SendOpts = send_opts() + send_opts() = [send_opt()] + send_opt() = {context, string()} | {timeout, pos_integer()} | {extra, term()} | {community, community()} | {sec_model, sec_model()} | {sec_name, string()} | {sec_level, sec_level()} | {max_message_size, pos_integer()} ReqId = integer() Reason = term()

Asynchronous get-bulk-request (See RFC1905).

+

The reply will be delivered to the user through a call - to the snmpm_user callback function handle_pdu.

-

The Expire time indicates for how long the request is - valid (after which the manager is free to delete it).

+ to the snmpm_user callback function handle_pdu.

+ +

The send option timeout specifies for how long the request is + valid (after which the manager is free to delete it).

+ +

The send option extra specifies an opaque data structure + passed on to the net-if process. The net-if process included in this + application makes no use of this info, so the only use for it + in such a configuration (when using the built in net-if) would + be tracing.

+ +

Some of the send options (community, sec_model, + sec_name, sec_level and max_message_size) + are override options. That is, + for this request, they override any configuration done + when the agent was registered.

-- cgit v1.2.3