\"     $NetBSD: isns.3,v 1.2 2011/01/16 08:00:01 wiz Exp $
\"
\" Copyright (c) 2004,2009 The NetBSD Foundation, Inc.
\" All rights reserved.
\"
\" This code is derived from software contributed to The NetBSD Foundation
\" by Wasabi Systems, Inc.
\"
\" Redistribution and use in source and binary forms, with or without
\" modification, are permitted provided that the following conditions
\" are met:
\" 1. Redistributions of source code must retain the above copyright
\"    notice, this list of conditions and the following disclaimer.
\" 2. Redistributions in binary form must reproduce the above copyright
\"    notice, this list of conditions and the following disclaimer in the
\"    documentation and/or other materials provided with the distribution.
\"
\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
\" POSSIBILITY OF SUCH DAMAGE.
Dd October 1, 2009
Dt ISNS 3
Os
Sh NAME
Nm isns
Nd iSNS protocol support library
Sh LIBRARY
Lb libisns
Sh SYNOPSIS
In isns.h
Ft int
Fn isns_init "ISNS_HANDLE *h" "int is_server"
Ft void
Fn isns_stop "ISNS_HANDLE h"
Ft int
Fn isns_add_servercon "ISNS_HANDLE h" "int fd" "struct addrinfo *ai"
Ft int
Fn isns_init_reg_refresh "ISNS_HANDLE h" "const char *node" "int interval"
Ft ISNS_TRANS
Fn isns_new_trans "ISNS_HANDLE h" "uint16_t func_id" "uint16_t pdu_flags"
Ft int
Fn isns_add_tlv "ISNS_TRANS t" "uint32_t tag" "int data_len" "const void *data_p"
Ft int
Fn isns_add_string "ISNS_TRANS t" "uint32_t tag" "const char *s"
Ft int
Fn isns_send_trans "ISNS_TRANS t" "const struct timespec *timeout_p" "uint32_t *status_p"
Ft int
Fn isns_get_tlv "ISNS_TRANS t" "int which_tlv" "uint32_t *tag_p" "int data_len_p" "void **data_pp"
Ft void
Fn isns_free_trans "ISNS_TRANS t"
Sh DESCRIPTION
The
Nm
library exports an API that simplifies Internet Storage Name
Service (iSNS) client implementations.
The API defines a transactional model in support of:
Pp
Bl -bullet -width 3n -offset indent -compact
It
generating iSNS messages composed of iSNS attributes expressed in
Tag-Length-Value (TLV) data format
It
submitting iSNS Protocol (iSNSP) messages
It
optionally waiting for iSNSP responses
El
Pp
Nm
does not currently support receipt of iSNS Heartbeat messages, State Change
Notification (SCN) messages, or Entity Status Inquiry (ESI) messages.
Sh INITIALIZATION
An iSNS client that uses
Nm
must call
Fn isns_init
to initialize the iSNS environment.
This call will create a thread to handle client-server communication, and
as such should only be called when thread creation is appropriate (such
as after a daemonized program forks).
Pp
The value passed as
Ar is_server
is used to set iSNSP message format Flags
"Sender is the iSNS client" (bit position 16) and "Sender is the iSNS server"
(bit position 17).
For now the value 0 (zero) should be passed for
Ar is_server .
The value returned in
Ar h
should be considered opaque by the caller.
This value is passed unchanged to
Fn isns_add_servercon ,
Fn isns_init_reg_refresh ,
Fn isns_stop ,
and
Fn isns_new_trans .
Pp
Fn isns_stop
should be called when the iSNS environment is no longer needed.
This call will kill any threads created by
Fn isns_init .
Sh CONFIGURATION
Following initialization,
Fn isns_add_servercon
should be used to make the iSNS environment aware of the iSNS
server to which iSNSP queries and requests are to be sent.
This routine should not be called by a program acting as an iSNS server.
Pp
A connected TCP socket descriptor is passed as parameter
Ar fd .
Parameter
Ar ai
is the address of the remote TCP endpoint.
It is included so that reconnection may be attempted by
Nm
in the event that the TCP connection is broken.
Pp
Certain iSNS servers will limit registration lifetimes, and will
refresh registrations after any request from a given iSNS entity.
The
Fn isns_init_reg_refresh
function offers a way for
Nm
to refresh registrations on behalf of the iSNS client.
Pp
Parameter
Ar node
is the
Dq iSCSI Name
attribute used for the periodic queries.
It should be the name of an iSCSI node within the registered iSNS entity.
The desired refresh interval, in seconds, is passed in parameter
Ar interval .
Sh TRANSACTIONS
Fn isns_new_trans
creates new iSNS transactions.
Pp
Parameter
Ar func_id
is used as the iSNSP message id.
Parameter
Ar pdu_flags
is used to set iSNSP message format Flags and is
exposed to allow callers to set flag "Replace flag" (bit position 19).
This provides callers with a way
to specify whether a Device Attribute Registration Request is intended to
update or replace an existing registration.
This is currently the only use defined for parameter
Ar pdu_flags .
Pp
Once a new transaction has been created, callers can specify iSNS attributes
used for registration and query requests.
TLV data may be added using either
Fn isns_add_tlv
or
Fn isns_add_string .
Pp
Parameter
Ar tag
is the iSNS Tag corresponding to the attribute being added.
Parameter
Ar data_len
is the length of the attribute value.
Parameter
Ar data_p
references the attribute value.
The caller does not need to handle iSNS attribute 4-byte alignment requirements.
This is handled by the iSNS environment on behalf of the caller.
Fn isns_add_string
may be used if the attribute value is a NUL terminated C string.
Pp
Once a transaction has been populated with any required TLV data,
Fn isns_send_trans
can be used to submit an iSNSP registration or query message.
Pp
Callers that submit iSNSP query messages may need to wait for returned data.
Fn isns_send_trans
supports bounded waits.
Successful waits, those that do not time out, return the iSNSP response
status code received in the iSNSP response message.
If a wait does time out, the value of
Ar status_p
is undefined.
Callers that do not need to wait for returned data can simply
pass
Dv NULL
for parameter
Ar timeout_p .
Callers should set parameter
Ar status_p
to
Dv NULL
if not waiting.
Pp
Fn isns_get_tlv
is used to retrieve TLV data returned in a transaction.
The first call to
Fn isns_get_tlv
should pass the value
Dv ISNS_TLV_FIRST
for parameter
Ar which_tlv .
Each subsequent TLV can be retrieved by passing in
Dv ISNS_TLV_NEXT
in place of
Dv ISNS_TLV_FIRST .
Pp
When a caller is done with a transaction, having submitted either a
registration or a query message and retrieved any returned TLV data,
Fn isns_free_trans
should be used to release resources used by the transaction.
Sh RETURN VALUES
Fn isns_init ,
Fn isns_add_servercon ,
Fn isns_init_reg_refresh ,
Fn isns_add_tlv ,
Fn isns_add_string ,
and
Fn isns_send_trans
return 0 on success, or \-1 on failure.
Fn isns_new_trans
returns 0 on success, or
Dv ISNS_INVALID_TRANS
on failure.
Fn isns_get_tlv
returns 0 on success, or
Er ENOENT
if there are no TLVs to retrieve.
Sh HISTORY
Nm
first appeared in
Nx 6.0 .
The
Nm
implementation was contributed to the
Nx
Foundation by Wasabi Systems, Inc.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.