NAME

XDI::Connection - XDI Connection and iname resolution object

VERSION

Version 0.01

SYNOPSIS

use XDI;

my $xdi = new XDI;
my $c = $xdi->connect();

..

my $xdi_hash = {
	'from' => '=my_graph',
	'from_graph' => '@xdiserver'
};

my $xdi = XDI->new($hash);
my $c = $xdi->connect({	target => '=other_graph', secret => "foosh"});

EXPORTS

iname_lookup
inumber_lookup
lookup

XDI::Connection

Set the target graph and shared secret for the object. Default behavior is to do a lookup on target to get the inumber and server URI that is hosting the graph. You can provide either an iname or an inumber as the target value, but the current services do not allow an inumber to be resolved back to an iname.

DESCRIPTION

The XDI perl module provides iname resolution and provides an http post method to send messages

Notation and Conventions

$xdi	Root object defining identity of querier
$c	Connection object defining graph target and permissions
$msg	Message object for XDI messages
$hash	Reference to a hash of key/attribute values
$target	iname or inumber of the graph which is queried
$secret	Shared secret for access to the I<target> graph

Usage Outline

The primary method for creating a Connection object is via the connect() method of the XDI object

$c = $xdi->connect();

You can pass any XDI::Connection initialization parameters to connect()

$hash = {
	target => E<lt>iname|inumberE<gt>,  # eg: =my_personal_cloud
	secret => $secret
};

$c = $xdi->connect($hash);

Given an iname, the default behavior for XDI is to attempt to resolve the iname to it's corresponding inumber using the iname resolution service at xri2xdi.net. This service also returns the URI to the graph that is authoritative for said iname, during testing and development that often proves inconvenient so you can override this behavior

$c->resolve(0);

Of course, if you do that, you will have to specify the URI of the graph to which you are sending a query

$c->server("http://example/=my_personal_cloud");

You may have noticed that we haven't actually connected to anything yet. I reserve the right to make checking the target graph for a valid link contract part of the connection process

secret

XDI security policy is currently under discussion by the XDI Technical Committee so the placeholder for a more robust policy is to use a shared secret. Please note that the policy allows for arbitrarily complex expressions and Javascript is proposed for the expression syntax. https://wiki.oasis-open.org/xdi/XdiPolicyExpression As the policy matures, I expect to need to update the client

$graph = $c->post($msg);

The result is a JSON encoded representation of the nodes requested in the $get operation. Other operations will return an empty hash {} upon success. Default behavior is to automatically convert the JSON to a perl hash object

SUBROUTINES/METHODS

XDI and it's members support the common PERL OO-style syntax via AUTOLOAD

Constructor

Generally, the constructor for the XDI::Connection object is not called directly.

Instance variables

Instance variables are only accessible through the respective getter/setter methods. Allowed variables are:

target #iname/inumber (string)

secret #target graph's shared secret (string)

resolve #perform automatic lookup on target (boolean)

server #url (string)

context #include contexts nodes in results (boolean)

message

$msg = $c->message();

As usual, you can pass valid message constructor parameters to XDI::Connection::message

$msg = $c->message({ link_contract => '=!1111'});

post

$result = $c->post($msg);
$result = $c->post($xdi_string);

post accepts either a XDI::Message object or a perl string as a parameter and returns a perl hash object. Currently $add operations return an empty hash {}. In case of an HTTP or XDI error, undef is returned. The error message can be accessed by encapsulating the post in an eval block

eval {
	$result = $c->post($msg);
};

if ($@) {
	# error handler
}

iname_lookup

$tuple = iname_lookup('=tester');

inumber_lookup

$tuple = inumber_lookup('=!3436.F6A6.3644.4D74');

lookup

$tuple = lookup(<iname | inumber>);

$tuple is [iname,inumber,url] # for inumber_lookup, iname will be undef

lookup, iname_lookup, and inumber_lookup are convenience functions to call the XDI resolution service built into XDI::Connection. lookup uses a simple method to determine whether the parameter is an inumber or iname and then performs the appropriate x_lookup

Technically, these are both XDI messages to the $XRI_AUTHORITY server but x_lookup encapsulates the whole process into an anonymous XDI message.

set_resolution_authority

Since the XDI resolution process is still in development, set_resolution_authority allows the developer to specify explicitly the resolution server. In case the resolution URI changes, this will allow discovery to continue until the module can be updated

AUTHOR

Mark Horstmeier <solargroovey@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2007-2012 Kynetx, Inc.

The perl XDI client is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

cpanm XDI

perl -MCPAN -e shell
install XDI