NAME
isns —
iSNS protocol support
library
LIBRARY
Internet Storage Name Service Library (libisns, -lisns)
SYNOPSIS
#include <isns.h>
int
isns_init(
ISNS_HANDLE
*h,
int is_server);
void
isns_stop(
ISNS_HANDLE
h);
int
isns_add_servercon(
ISNS_HANDLE
h,
int fd,
struct addrinfo *ai);
int
isns_init_reg_refresh(
ISNS_HANDLE
h,
const char *node,
int interval);
ISNS_TRANS
isns_new_trans(
ISNS_HANDLE
h,
uint16_t func_id,
uint16_t pdu_flags);
int
isns_add_tlv(
ISNS_TRANS
t,
uint32_t tag,
int data_len,
const void *data_p);
int
isns_add_string(
ISNS_TRANS
t,
uint32_t tag,
const char *s);
int
isns_send_trans(
ISNS_TRANS
t,
const struct timespec
*timeout_p,
uint32_t
*status_p);
int
isns_get_tlv(
ISNS_TRANS
t,
int which_tlv,
uint32_t *tag_p,
int data_len_p,
void **data_pp);
void
isns_free_trans(
ISNS_TRANS
t);
DESCRIPTION
The
isns library exports an API that simplifies Internet
Storage Name Service (iSNS) client implementations. The API defines a
transactional model in support of:
- generating iSNS messages
composed of iSNS attributes expressed in Tag-Length-Value (TLV) data
format
- submitting iSNS Protocol
(iSNSP) messages
- optionally waiting for iSNSP
responses
isns does not currently support receipt of iSNS Heartbeat
messages, State Change Notification (SCN) messages, or Entity Status Inquiry
(ESI) messages.
INITIALIZATION
An iSNS client that uses
isns must call
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).
The value passed as
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
is_server. The value
returned in
h should be considered opaque by the caller.
This value is passed unchanged to
isns_add_servercon(),
isns_init_reg_refresh(),
isns_stop(), and
isns_new_trans().
isns_stop() should be called when the iSNS environment is no
longer needed. This call will kill any threads created by
isns_init().
CONFIGURATION
Following initialization,
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.
A connected TCP socket descriptor is passed as parameter
fd. Parameter
ai is the address of
the remote TCP endpoint. It is included so that reconnection may be attempted
by
isns in the event that the TCP connection is broken.
Certain iSNS servers will limit registration lifetimes, and will refresh
registrations after any request from a given iSNS entity. The
isns_init_reg_refresh() function offers a way for
isns to refresh registrations on behalf of the iSNS client.
Parameter
node is the “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
interval.
TRANSACTIONS
isns_new_trans() creates new iSNS transactions.
Parameter
func_id is used as the iSNSP message id.
Parameter
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
pdu_flags.
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
isns_add_tlv() or
isns_add_string().
Parameter
tag is the iSNS Tag corresponding to the
attribute being added. Parameter
data_len is the length
of the attribute value. Parameter
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.
isns_add_string() may be used if the attribute
value is a NUL terminated C string.
Once a transaction has been populated with any required TLV data,
isns_send_trans() can be used to submit an iSNSP
registration or query message.
Callers that submit iSNSP query messages may need to wait for returned data.
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
status_p is undefined. Callers that do not need to wait
for returned data can simply pass
NULL
for parameter
timeout_p. Callers should set parameter
status_p to
NULL
if not waiting.
isns_get_tlv() is used to retrieve TLV data returned in a
transaction. The first call to
isns_get_tlv() should pass
the value
ISNS_TLV_FIRST
for parameter
which_tlv. Each subsequent TLV can be retrieved by
passing in
ISNS_TLV_NEXT
in place of
ISNS_TLV_FIRST
.
When a caller is done with a transaction, having submitted either a registration
or a query message and retrieved any returned TLV data,
isns_free_trans() should be used to release resources used
by the transaction.
RETURN VALUES
isns_init(),
isns_add_servercon(),
isns_init_reg_refresh(),
isns_add_tlv(),
isns_add_string(), and
isns_send_trans()
return 0 on success, or -1 on failure.
isns_new_trans()
returns 0 on success, or
ISNS_INVALID_TRANS
on
failure.
isns_get_tlv() returns 0 on success, or
ENOENT
if there are no TLVs to retrieve.
HISTORY
isns first appeared in
NetBSD 6.0. The
isns implementation was contributed to the
NetBSD Foundation by Wasabi Systems, Inc.