NAME
IO::Socket::TIPC::Sockaddr - struct sockaddr_tipc class
SYNOPSIS
use IO::Socket::TIPC::Sockaddr;DESCRIPTION
TIPC Sockaddrs are used with TIPC sockets, to specify local or remote endpoints for communication. They are used in the bind(), connect(), sendto() and recvfrom() calls.
Sockaddrs can be broken down into 3 address-types, "name", "nameseq" and "id". the Programmers_Guide.txt (linked to in REFERENCES) explains the details much better than I ever could, I suggest reading it before trying to use this module. Also, the EXAMPLES section is useful for getting a feel for how this module works.
CONSTRUCTOR
...->new ( "string", key=>value, key=>value... )
...->new ( key=>value, key=>value... )
...->new_from_data ( $binary_data )Creates an "IO::Socket::TIPC::Sockaddr" object, which is really just a bunch of fluff to manage C "struct sockaddr_tipc" values easily.
Use the new_from_data constructor if you want to wrap this class around some sockaddr_tipc data you obtained from somewhere else. (for instance, from the getpeername builtin.)
Use the new() constructor to create a new sockaddr object. It optionally takes a string as its first argument. Any other arguments are in the form of Key => Value pairs.
Initial String Argument (optional)
You can pass any type of TIPC address as a string, to fill in most of the below values for you. This is a very useful way to save lots of typing, and keeps it more readable. Here is a list of possible string arguments, and their hash-parameter equivalents:
"<1.2.3:4>" is equivalent to:
AddrType => TIPC_ADDR_ID,
Zone => 1,
Cluster => 2,
Node => 3,
Ref => 4
"{1, 2}" is equivalent to:
AddrType => TIPC_ADDR_NAME,
Type => 1,
Instance => 2
"{1, 2, 3}" is equivalent to:
AddrType => TIPC_ADDR_NAMESEQ,
Type => 1,
Lower => 2,
Upper => 3Of course, noone has to spell the fields out in such excruciating detail (you can pass the same strings in Id/Name/Nameseq parameters), but it illustrates my point nicely.
The string does not define everything useful about the address... consider specifying the Scope parameter for arguments to bind, and the Domain parameter for names you plan to connect to.
AddrType
This tells Sockaddr whether to create an id, name or nameseq address. The default is guessed from the other arguments it was given; pass the AddrType argument to make it explicit. In practice, this is rarely (never?) needed.
If the right constants were imported, you can pass the following arguments: TIPC_ADDR_ID, TIPC_ADDR_NAME, TIPC_ADDR_NAMESEQ, or TIPC_ADDR_MCAST (which is an alias for TIPC_ADDR_NAMESEQ). Otherwise, you can just say "id", "name" or "nameseq", these will work equally well.
Scope
Valid for name and nameseq addresses. Specifies how loudly to advertise the name/nameseq, to the rest of the network. The default is TIPC_NODE_SCOPE.
If the right constants were imported, you can pass the following arguments: TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, or TIPC_NODE_SCOPE. Otherwise, you can just say "zone", "cluster" or "node", which will work equally well.
Id
Defines an id address. An id address has the format "<Zone.Cluster.Node:Ref>". With the Id parameter, you can specify the "<Zone.Cluster.Node>" portion of that address, either with a string (like "<1.2.3>") or as an unsigned 32-bit integer. Alternately, you can define the whole thing, Ref included, as a string (like "<1.2.3:4>"). This is a useful way to avoid having to specify the Ref, Zone, Cluster, and Node parameters individually.
Ref
Valid for id addresses. This 32-bit field is usually assigned randomly by the operating system, and only needs to be set when you are attempting to connect to someone else.
Zone
Valid for id addresses. This 8-bit field defines the Zone portion of the Id address. See the Id parameter.
Cluster
Valid for id addresses. This 12-bit field defines the Cluster portion of the Id address. See the Id parameter.
Node
Valid for id addresses. This 12-bit field defines the Node portion of the Id address. See the Id parameter.
Name
Defines a name address. A name address comprises two fields, Type and Instance, 32 bits each. It has the format "{Name, Instance}". Name addresses also have a Domain flag, which is used in connecting, to specify where to start looking for the server.
The Name parameter is useful for defining a name address all in one go (minus the Domain). Pass it a string, like "{1, 2}", to avoid having to specify the Type and Instance parameters individually.
Type
Required for name and nameseq addresses. This 32-bit field defines the Type portion of the address.
Instance
Required for name addresses. This 32-bit field defines the Instance portion of the address.
Domain
Valid for name addresses. This 32-bit field defines the starting point, when searching for a server by name. You can pass it an integer, or a TIPC address string, of the form "<1.2.3>".
Nameseq
Defines a nameseq address. A nameseq address comprises three fields, Type, Lower and Upper, 32 bits each. The Lower and Upper attributes define a range of Instance values (see Name).
nameseq addresses have the format "{Type, Lower, Upper}".
The Nameseq parameter is useful for defining a nameseq address all in one go. Pass it a string, like "{1, 2, 3}", to avoid having to specify the Type, Lower and Upper parameters individually.
Lower
Required for nameseq addresses. This 32-bit field defines the lower end of an Instance range. If unspecified, it defaults to Upper, resulting in a "range" of 1.
Upper
Required for nameseq addresses. This 32-bit field defines the upper end of an Instance range. If unspecified, it defaults to Lower, resulting in a "range" of 1.
METHODS
stringify()
stringify returns a string representing the sockaddr. These strings are the same as the ones used in the TIPC documentation, see Programmers_Guide.txt (linked to in REFERENCES). Depending on the address type, it will return something that looks like one of:
"<1.2.3:4>" # ID, addr = 1.2.3, ref = 4
"{4242, 100}" # NAME, type = 4242, instance = 100
"{4242, 100, 101}" # NAMESEQ, type = 4242, range 100-101Note that these strings are intended for use as shorthand, with someone familiar with TIPC. They do not include all the fields of the sockaddr structure, and sometimes the hidden fields are important. In particular, they are missing the Scope and Domain fields, which affect how far away binding/connecting may occur for names and nameseqs. If you need to store an address for reuse, you are better off reusing the Sockaddr object itself, rather than storing one of these strings.
get/set routines
The C structure looks like this (minor edits for clarity):
struct sockaddr_tipc {
unsigned short family;
unsigned char addrtype;
signed char scope;
union {
struct {
__u32 ref;
__u32 node;
} id;
struct {
__u32 type;
__u32 lower;
__u32 upper;
} nameseq;
struct {
struct {
__u32 type;
__u32 instance;
} name;
__u32 domain;
} name;
} addr;
};Each of these fields has methods to get and set it. The only exception is "family", which is always set to AF_TIPC, and has very good reasons for being read-only.
An exhaustive list of these methods follows. All functions return integers, "val" means an unsigned integer argument, "<1.2.3>" means a string-address argument (obviously).
- global stuff
-
get_family() get_addrtype() set_addrtype(val) get_scope() set_scope(val) - TIPC_ADDR_ID stuff
-
get_ref() set_ref(val) get_id() set_id(val) or set_id("<1.2.3>") get_zone() set_zone(val) get_cluster() set_cluster(val) get_node() set_node(val)NOTE: for id-style addresses, direct access to the address as a whole (id) is allowed, as well as its constituent components (zone, cluster, and node). This may cause confusion, since the whole address is called "node" in the C structure, but "node" refers to only a portion of the address here.
- TIPC_ADDR_NAME stuff
-
get_ntype() set_ntype(val) get_instance() set_instance(val) get_domain() set_domain(val) or set_domain("<1.2.3>") - TIPC_ADDR_NAMESEQ stuff
-
get_stype() set_stype(val) get_lower() set_lower(val) get_upper() set_upper(val) - Type helpers
-
get_type() set_type(arg)The get_type/set_type functions call either get_ntype/set_ntype, or get_stype/set_stype, depending on whether the addrtype is name or nameseq.
SUBROUTINES (non-methods)
tipc_zone(int)
Unpacks the Zone from a TIPC address (integer). You can also pass it a string address, like "<1.2.3>". Returns the zone as an integer. Example below.
tipc_cluster(int)
Unpacks the Cluster from a TIPC address (integer). You can also pass it a string address, like "<1.2.3>". Returns the cluster as an integer.
my $zone = tipc_zone(0x01002003); # $zone is now set to 1
my $cluster = tipc_zone(0x01002003); # $cluster is now set to 2
my $node = tipc_zone(0x01002003); # $node is now set to 3
printf("<%i.%i.%i>\n",
$zone, $cluster, $node); # prints <1.2.3>tipc_node(int)
Unpacks the Node from a TIPC address (integer). You can also pass it a string address, like "<1.2.3>". Returns the node as an integer. Example above.
tipc_addr(int)
Packs a zone, cluster and node into a tipc address. You can also pass it a "<1.2.3>" string address.
my $addr = tipc_addr($zone, $cluster, $node);
printf("0x%x\n", $addr); # prints 0x01002003tipc_parse_string(hashref, string)
Given a string that looks like "<1.2.3:4>", "<1.2.3>", "{1, 2}", or "{1, 2, 3}", chop it into its components. Puts the components into appropriately named keys in hashref, like Zone, Cluster, Node, Ref, Type, Instance, Upper, Lower. It also guesses the AddrType of the string you passed. Returns 1 on success, croaks on error.
my $href = {};
tipc_parse_string($href, "<1.2.3:4>");
printf("Address <%i.%i.%i:%i> is of type %s\n",
@$href{"Zone", "Cluster", "Node", "Ref", "AddrType"});
# prints "Address <1.2.3:4> is of type id\n"This is a function which new() uses internally, to turn user provided garbage into some values it can actually use. There is no need to call it directly, unless you want to use the same parser for some other reason, like input checking.
EXPORT
None by default.
Exportable subroutines
tipc_addr
tipc_zone
tipc_cluster
tipc_node
tipc_parse_stringEXAMPLES
In TIPC, there are 3 types of sockaddrs. Here are examples for all 3.
Name sockaddr: creation
You can use name sockets in the following manner:
$name = IO::Socket::TIPC::Sockaddr->new(
AddrType => "name",
Type => 4242,
Instance => 1005);Or
$name = IO::Socket::TIPC::Sockaddr->new(
AddrType => "name",
Name => "{4242, 1005}");Or, even
$name = IO::Socket::TIPC::Sockaddr->new("{4242, 1005}");With all address types, the stringify method will return something readable.
$string = $name->stringify();
# stringify returns "{4242, 1005}"Nameseq sockaddr: creation
You can use nameseq sockets in the following manner:
$nameseq = IO::Socket::TIPC::Sockaddr->new(
AddrType => "nameseq",
Type => 4242,
Lower => 100,
Upper => 1000);Or, more simply,
$nameseq = IO::Socket::TIPC::Sockaddr->new(
AddrType => "nameseq",
Name => "{4242, 100, 1000}");Or even just
$nameseq = IO::Socket::TIPC::Sockaddr->new("{4242, 100, 1000}");If Upper is unspecified, it defaults to Lower. If Lower is unspecified, it defaults to Upper. You must specify at least one.
$nameseq = IO::Socket::TIPC::Sockaddr->new(
AddrType => "nameseq",
Type => 4242,
Lower => 100);With all address types, the stringify method will return something readable.
$string = $nameseq->stringify();
# stringify returns "{4242, 100, 100}"Id sockaddr: creation
You can use id sockets in the following manner:
$id = IO::Socket::TIPC::Sockaddr->new(
AddrType => "id",
Zone => 1,
Cluster => 2,
Node => 3,
Ref => 5000);Or, more simply,
$id = IO::Socket::TIPC::Sockaddr->new(
AddrType => "id",
Id => "<1.2.3>",
Ref => 5000);Or, more simply,
$id = IO::Socket::TIPC::Sockaddr->new(
AddrType => "id",
Id => "<1.2.3:5000>");Or even just
$id = IO::Socket::TIPC::Sockaddr->new("<1.2.3:5000>");
With all address types, the stringify method will return something readable.
$string = $id->stringify();
# stringify returns "<1.2.3:5000>"BUGS
Probably many. Please report any bugs you find to the author. A TODO file exists, which lists known unimplemented and broken stuff.
REFERENCES
See also:
IO::Socket, Socket, IO::Socket::TIPC, http://tipc.sf.net/. The Programmers_Guide.txt is particularly helpful, and is available off the SourceForge site. See http://tipc.sf.net/doc/Programmers_Guide.txt, or http://tipc.sf.net/documentation.html.
AUTHOR
Mark Glines <mark-tipc@glines.org>
COPYRIGHT AND LICENSE
This module is licensed under a dual BSD/GPL license, the same terms as TIPC itself.