6 use vars qw( $VERSION @ISA $AUTOLOAD $DEBUG $PROTO_VERSION $POST_URL
7 @EXPORT_OK %EXPORT_TAGS ); # @EXPORT
15 use Net::XRC::Response;
17 use Net::XRC::Data::list;
19 #use Net::XRC::Data::int;
20 use Net::XRC::Data::string;
21 use Net::XRC::Data::boolean;
22 #use Net::XRC::Data::null;
23 use Net::XRC::Data::bytes;
24 #use Net::XRC::Data::list;
25 use Net::XRC::Data::complex;
29 # Items to export into callers namespace by default. Note: do not export
30 # names by default without a very good reason. Use EXPORT_OK instead.
31 # Do not simply export all your public functions/methods/constants.
33 # This allows declaration use Net::XRC ':all';
34 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
36 %EXPORT_TAGS = ( 'types' => [ qw(
37 string boolean bytes complex
40 @EXPORT_OK = ( @{ $EXPORT_TAGS{'types'} } );
49 $POST_URL = 'https://xrc.everyone.net/ccc/xrc';
53 my $ua = LWP::UserAgent->new;
54 $ua->agent("Net::XRC/$VERSION");
58 Net::XRC - Perl extension for Everyone.net XRC Remote API
62 use Net::XRC qw(:types); # pulls in type subroutines:
63 # string, boolean, bytes
65 my $xrc = new Net::XRC (
66 'clientID' => '1551978',
67 'password' => 'password',
72 my $response = $xrc->noop; #returns Net::XRC::Response object
73 die $response->error unless $response->is_success;
77 my $username = 'tofu_beast';
78 my $response = $xrc->isAccountName( $clientID, $username );
79 die $response->error unless $response->is_success;
80 my $available = $res->content;
82 print "$username is available\n";
84 print "$username is not available\n";
87 # isAccountName (numeric)
88 # note the use of string() to force the datatype to string, which would
89 # otherwise be (incorrectly) auto-typed as int
91 my $numeric_username = '54321';
92 my $response = $xrc->isAccountName( $clientID, string($numeric_username) );
93 die $response->error unless $response->is_success;
94 my $available = $res->content;
96 print "$numeric_username is available\n";
98 print "$numeric_username is not available\n";
103 my $username = 'tofu_beast';
104 my $response = $xrc->createUser( $clientID, [], $username, 'password' );
105 die $response->error unless $response->is_success;
106 my $uid = $response->content;
107 print "$username created: uid $uid\n";
109 # createUser (numeric)
110 # note the use of string() to force the datatype to string, which would
111 # otherwise be (incorrectly) auto-typed as int
113 my $numeric_username = '54321';
114 my $response = $xrc->createUser( $clientID,
116 string($numeric_username),
119 die $response->error unless $response->is_success;
120 my $uid = $response->content;
121 print "$numeric_username created: uid $uid\n";
125 $response = $src->setUserPassword( $clientID, 'username', 'new_password' );
126 if ( $response->is_success ) {
127 print "password change sucessful";
129 print "error changing password: ". $response->error;
134 $response = $src->suspendUser( $clientID, 'username' );
135 if ( $response->is_success ) {
136 print "user suspended";
138 print "error suspending user: ". $response->error;
143 $response = $src->unsuspendUser( $clientID, 'username' );
144 if ( $response->is_success ) {
145 print "user unsuspended";
147 print "error unsuspending user: ". $response->error;
152 $response = $src->deleteUser( $clientID, 'username' );
153 if ( $response->is_success ) {
154 print "user deleted";
156 print "error deleting user: ". $response->error;
162 This module implements a client interface to Everyone.net's XRC Remote API,
163 enabling a perl application to talk to Everyone.net's XRC server.
164 This documentation assumes that you are familiar with the XRC documentation
165 available from Everyone.net (XRC-1.0.5.html or later).
167 A new Net::XRC object must be created with the I<new> method. Once this has
168 been done, all XRC commands are accessed via method calls on the object.
174 =item new OPTION => VALUE ...
176 Creates a new Net::XRC object. The I<clientID> and I<password> options are
183 my $class = ref($proto) || $proto;
184 my $self = { 'version' => $PROTO_VERSION,
187 bless($self, $class);
190 =item AUTOLOADed methods
192 All XRC methods are available. See the XRC documentation for methods,
193 arguments and return values.
195 Responses are returned as B<Net::XRC::Response> objects. See
196 L<Net::XRC::Response>.
198 XRC I<int> arguments are auto-recognized as numeric perl scalars.
200 XRC I<string> arguments are auto-recognized as all other perl scalars, or
201 you can import and use the B<string()> subroutine to ensure your string is
202 not mistaken as an I<int>.
204 XRC I<null> are auto-recognized as undefined ("undef") perl scalars.
206 XRC I<boolean> arguements must be explicitly specified as B<boolean()>.
208 XRC I<bytes> arguments must be explicitly specified as B<bytes()>.
210 XRC I<list> arguments are passed and returned as perl array references.
212 XRC I<complex> arguments are passed and returned as perl hash references,
213 with an additional I<_type> key denotating the argument type
214 (I<AliasInfo>, I<EmailClientSummary>, I<WebmailPresentation>, I<Letter>).
215 Optionally, you may use the B<complex()> subroutine to construct them, as in:
216 C<complex('typename', \%hash)>.
223 $AUTOLOAD =~ s/.*://;
224 return if $AUTOLOAD eq 'DESTROY';
226 my $req = HTTP::Request->new( 'POST' => $POST_URL );
227 $req->content_type('application/x-eon-xrc-request');
230 join("\n", map { "$_:". $self->{$_} } keys %$self). #metadata
233 Net::XRC::Data::list->new(\@_)->encode
236 warn "\nPOST $POST_URL\n". $req->content. "\n"
239 my $res = $ua->request($req);
241 # Check the outcome of the response
242 if ($res->is_success) {
244 warn "\nRESPONSE:\n". $res->content
247 my $response = new Net::XRC::Response $res->content;
249 warn Dumper( $response )
255 #print $res->status_line, "\n";
256 die $res->status_line, "\n";
261 sub string { new Net::XRC::Data::string( shift ); }
262 sub boolean { new Net::XRC::Data::boolean( shift ); }
263 sub bytes { new Net::XRC::Data::bytes( shift ); }
269 $hr = { '_type' => shift,
273 new Net::XRC::Data::complex( $hr );
280 Needs better documentation.
282 Data type auto-guessing can get things wrong for all-numeric strings. I<bool>
283 and I<bytes> types must be specified explicitly. Ideally each method should
284 have a type signature so manually specifying data types would never be
287 The "complex" data types (I<AliasInfo>, I<EmailClientSummary>,
288 I<WebmailPresentation>, I<Letter>) are untested.
292 L<Net::XRC::Response>,
293 Everyone.net XRC Remote API documentation (XRC-1.0.5.html or later)
297 Ivan Kohler E<lt>ivan-xrc@420.amE<gt>
299 =head1 COPYRIGHT AND LICENSE
301 Copyright (C) 2005 Ivan Kohler
303 This library is free software; you can redistribute it and/or modify
304 it under the same terms as Perl itself.