Net::PH - CCSO Nameserver Client class
SYNOPSIS
use Net::PH;
$ph = Net::PH->new("some.host.name",
Port => 105,
Timeout => 120,
Debug => 0);
if($ph) {
$q = $ph->query({ field1 => "value1" },
[qw(name address pobox)]);
if($q) {
}
}
# Alternative syntax
if($ph) {
$q = $ph->query('field1=value1',
'name address pobox');
if($q) {
}
}
DESCRIPTION
Net::PH is a class implementing a simple Nameserver/PH
client in Perl as described in the CCSO Nameserver --
Server-Client Protocol. Like other modules in the Net::
family the Net::PH object inherits methods from Net::Cmd.
CONSTRUCTOR
new ( [ HOST ] [, OPTIONS ])
$ph = Net::PH->new("some.host.name",
Port => 105,
Timeout => 120,
Debug => 0
);
This is the constructor for a new Net::PH object. HOST
is the name of the remote host to which a PH
connection is required.
If HOST is not given, then the SNPP_Host specified in
Net::Config will be used.
OPTIONS is an optional list of named options which are
Port - Port number to connect to on remote host.
Timeout - Maximum time, in seconds, to wait for a
response from the Nameserver, a value of zero will
cause all IO operations to block. (default: 120)
Debug - Enable the printing of debugging information
to STDERR
METHODS
Unless otherwise stated all methods return either a true
or false value, with true meaning that the operation was a
success. When a method states that it returns a value,
failure will be returned as undef or an empty list.
query( SEARCH [, RETURN ] )
$q = $ph->query({ name => $myname },
[qw(name email schedule)]);
foreach $handle (@{$q}) {
foreach $field (keys %{$handle}) {
$c = ${$handle}{$field}->code;
$v = ${$handle}{$field}->value;
$f = ${$handle}{$field}->field;
$t = ${$handle}{$field}->text;
print "field:[$field] [$c][$v][$f][$t]\n" ;
}
}
Search the database and return fields from all
matching entries.
The SEARCH argument is a reference to a HASH which
contains field/value pairs which will be passed to the
Nameserver as the search criteria.
RETURN is optional, but if given it should be a
reference to a list which contains field names to be
returned.
The alternative syntax is to pass strings instead of
references, for example
$q = $ph->query('name=myname',
'name email schedule');
The SEARCH argument is a string that is passed to the
Nameserver as the search criteria. The strings being
data.
RETURN is optional, but if given it should be a string
which will contain field names to be returned.
Each match from the server will be returned as a HASH
where the keys are the field names and the values are
Net::PH:Result objects (code, value, field, text).
Returns a reference to an ARRAY which contains
references to HASHs, one per match from the server.
change( SEARCH , MAKE )
$r = $ph->change({ email => "*.domain.name" },
{ schedule => "busy");
Change field values for matching entries.
The SEARCH argument is a reference to a HASH which
contains field/value pairs which will be passed to the
Nameserver as the search criteria.
The MAKE argument is a reference to a HASH which
contains field/value pairs which will be passed to the
Nameserver that will set new values to designated
fields.
The alternative syntax is to pass strings instead of
references, for example
$r = $ph->change('email="*.domain.name"',
'schedule="busy"');
The SEARCH argument is a string to be passed to the
Nameserver as the search criteria. The strings being
passed should not contain any carriage returns, or
else the query command might fail or return invalid
data.
The MAKE argument is a string to be passed to the
Nameserver that will set new values to designated
fields.
Upon success all entries that match the search
criteria will have the field values, given in the Make
argument, changed.
login( USER, PASS [, ENCRYPT ])
$r = $ph->login('username','password',1);
encrypt a challenge text string provided by the
server, and the encrypted string will be sent back to
the server. If ENCRYPT is not given, or false then the
password will be sent in clear text (this is not
recommended)
logout()
$r = $ph->logout();
Exit login mode and return to anonymous mode.
fields( [ FIELD_LIST ] )
$fields = $ph->fields();
foreach $field (keys %{$fields}) {
$c = ${$fields}{$field}->code;
$v = ${$fields}{$field}->value;
$f = ${$fields}{$field}->field;
$t = ${$fields}{$field}->text;
print "field:[$field] [$c][$v][$f][$t]\n";
}
In a scalar context, returns a reference to a HASH.
The keys of the HASH are the field names and the
values are Net::PH:Result objects (code, value, field,
text).
In an array context, returns a two element array. The
first element is a reference to a HASH as above, the
second element is a reference to an array which
contains the tag names in the order that they were
returned from the server.
FIELD_LIST is a string that lists the fields for which
info will be returned.
add( FIELD_VALUES )
$r = $ph->add( { name => $name, phone => $phone });
This method is used to add new entries to the
Nameserver database. You must successfully call the
login manpage before this method can be used.
Note that this method adds new entries to the
database. To modify an existing entry use the change
manpage.
FIELD_VALUES is a reference to a HASH which contains
field/value pairs which will be passed to the
Nameserver and will be used to initialize the new
a reference, for example
$r = $ph->add('name=myname phone=myphone');
FIELD_VALUES is a string that consists of field/value
pairs which the new entry will contain. The strings
being passed should not contain any carriage returns,
or else the query command might fail or return invalid
data.
delete( FIELD_VALUES )
$r = $ph->delete('name=myname phone=myphone');
This method is used to delete existing entries from
the Nameserver database. You must successfully call
the login manpage before this method can be used.
Note that this method deletes entries to the database.
To modify an existing entry use the change manpage.
FIELD_VALUES is a string that serves as the search
criteria for the records to be deleted. Any entry in
the database which matches this search criteria will
be deleted.
id( [ ID ] )
$r = $ph->id('709');
Sends ID to the Nameserver, which will enter this into
its logs. If ID is not given then the UID of the user
running the process will be sent.
status()
Returns the current status of the Nameserver.
siteinfo()
$siteinfo = $ph->siteinfo();
foreach $field (keys %{$siteinfo}) {
$c = ${$siteinfo}{$field}->code;
$v = ${$siteinfo}{$field}->value;
$f = ${$siteinfo}{$field}->field;
$t = ${$siteinfo}{$field}->text;
print "field:[$field] [$c][$v][$f][$t]\n";
}
Returns a reference to a HASH containing information
about the server's site. The keys of the HASH are the
field names and values are Net::PH:Result objects
(code, value, field, text).
$r = $ph->quit();
Quit the connection
Q&A
How do I get the values of a Net::PH::Result object?
foreach $handle (@{$q}) {
foreach $field (keys %{$handle}) {
$my_code = ${$q}{$field}->code;
$my_value = ${$q}{$field}->value;
$my_field = ${$q}{$field}->field;
$my_text = ${$q}{$field}->text;
}
}
How do I get a count of the returned matches to my query?
$my_count = scalar(@{$query_result});
How do I get the status code and message of the last $ph
command?
$status_code = $ph->code;
$status_message = $ph->message;
SEE ALSO
the Net::Cmd manpage
AUTHORS
Graham Barr <gbarr@pobox.com> Alex Hristov
<hristov@slb.com>
ACKNOWLEDGMENTS
Password encryption code ported to perl by Broc Seib
<bseib@purdue.edu>, Purdue University Computing Center.
Otis Gospodnetic <otisg@panther.middlebury.edu> suggested
passing parameters as string constants. Some queries
cannot be executed when passing parameters as string
references.
Example: query first_name last_name email="*.domain"
COPYRIGHT
The encryption code is based upon cryptit.c, Copyright (C)
1988 by Steven Dorner, and Paul Pomes, and the University
of Illinois Board of Trustees, and by CSNET.
rights reserved. This program is free software; you can
redistribute it and/or modify it under the same terms as
Perl itself.