NAME

Net::XRC - Perl extension for Everyone.net XRC Remote API

SYNOPSIS

  use Net::XRC qw(:types);  # pulls in type subroutines:
                            # string, boolean, bytes

  my $xrc = new Net::XRC (
    'clientID' => '1551978',
    'password' => 'password',
  );

  # noop

  my $response = $xrc->noop; #returns Net::XRC::Response object
  die $response->error unless $response->is_success;

  # isAccountName

  my $username = 'tofu_beast';
  my $response = $xrc->isAccountName( $clientID, $username );
  die $response->error unless $response->is_success;
  my $available = $res->content;
  if ( $available ) {
    print "$username is available\n";
  } else {
    print "$username is not available\n";
  }

  # isAccountName (numeric)
  # note the use of string() to force the datatype to string, which would
  # otherwise be (incorrectly) auto-typed as int

  my $numeric_username = '54321';
  my $response = $xrc->isAccountName( $clientID, string($numeric_username) );
  die $response->error unless $response->is_success;
  my $available = $res->content;
  if ( $available ) {
    print "$numeric_username is available\n";
  } else {
    print "$numeric_username is not available\n";
  }

  # createUser 

  my $username = 'tofu_beast';
  my $response = $xrc->createUser( $clientID, [], $username, 'password' );
  die $response->error unless $response->is_success;
  my $uid = $response->content;
  print "$username created: uid $uid\n";

  # createUser (numeric)
  # note the use of string() to force the datatype to string, which would
  # otherwise be (incorrectly) auto-typed as int

  my $numeric_username = '54321';
  my $response = $xrc->createUser( $clientID,
                                   [],
                                   string($numeric_username),
                                   'password'
                                 );
  die $response->error unless $response->is_success;
  my $uid = $response->content;
  print "$numeric_username created: uid $uid\n";

  # setUserPassword

  $response = $src->setUserPassword( $clientID, 'username', 'new_password' );
  if ( $response->is_success ) {
    print "password change sucessful";
  } else {
    print "error changing password: ". $response->error;
  }

  # suspendUser

  $response = $src->suspendUser( $clientID, 'username' );
  if ( $response->is_success ) {
    print "user suspended";
  } else {
    print "error suspending user: ". $response->error;
  }

  # unsuspendUser

  $response = $src->unsuspendUser( $clientID, 'username' );
  if ( $response->is_success ) {
    print "user unsuspended";
  } else {
    print "error unsuspending user: ". $response->error;
  }

  # deleteUser

  $response = $src->deleteUser( $clientID, 'username' );
  if ( $response->is_success ) {
    print "user deleted";
  } else {
    print "error deleting user: ". $response->error;
  }

DESCRIPTION

This module implements a client interface to Everyone.net's XRC Remote API, enabling a perl application to talk to Everyone.net's XRC server. This documentation assumes that you are familiar with the XRC documentation available from Everyone.net (XRC-1.0.5.html or later).

A new Net::XRC object must be created with the new method. Once this has been done, all XRC commands are accessed via method calls on the object.

METHODS

new OPTION => VALUE ...

Creates a new Net::XRC object. The clientID and password options are required.

AUTOLOADed methods

All XRC methods are available. See the XRC documentation for methods, arguments and return values.

Responses are returned as Net::XRC::Response objects. See Net::XRC::Response.

XRC int arguments are auto-recognized as numeric perl scalars.

XRC string arguments are auto-recognized as all other perl scalars, or you can import and use the string() subroutine to ensure your string is not mistaken as an int.

XRC null are auto-recognized as undefined ("undef") perl scalars.

XRC boolean arguements must be explicitly specified as boolean().

XRC bytes arguments must be explicitly specified as bytes().

XRC list arguments are passed and returned as perl array references.

XRC complex arguments are passed and returned as perl hash references, with an additional _type key denotating the argument type (AliasInfo, EmailClientSummary, WebmailPresentation, Letter). Optionally, you may use the complex() subroutine to construct them, as in: complex('typename', \%hash).

BUGS

Needs better documentation.

Data type auto-guessing can get things wrong for all-numeric strings. bool and bytes types must be specified explicitly. Ideally each method should have a type signature so manually specifying data types would never be necessary.

The "complex" data types (AliasInfo, EmailClientSummary, WebmailPresentation, Letter) are untested.

SEE ALSO

Net::XRC::Response, Everyone.net XRC Remote API documentation (XRC-1.0.5.html or later)

AUTHOR

Ivan Kohler <ivan-xrc@420.am>

COPYRIGHT AND LICENSE

Copyright (C) 2005 Ivan Kohler

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.