package VXI11::Client;

use 5.014002;
use strict;
use warnings;

require Exporter;

our @ISA = qw(Exporter);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

# This allows declaration	use VXI11::Client ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = ( 'all' => [ qw(
	
) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

our @EXPORT = qw(
	vxi_startinterruptserver
	vxi_stopinterruptserver
 	vxi_open
	vxi_wait_for_interrupt	
);

our $VERSION = '0.01';

require XSLoader;
XSLoader::load('VXI11::Client', $VERSION);

sub vxi_enable_srq {
	return vxi_enable_srq_long($_[0], 1, $_[1]);
}


sub vxi_disable_srq {
	return vxi_enable_srq_long($_[0], 0 , "");
}


sub vxi_wait_for_interrupt {
	my %args = (
                timeout_ms => 250,
                @_
        );

	return vxi_wait_for_interrupt_long ($args{timeout_ms});
}


sub vxi_clear {
        my $self = shift;
	my %args = (
                waitforlock => 0,
                @_
        );
	return vxi_clear_long ($self, $args{waitforlock});
}


sub vxi_local {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_local_long ($self, $args{waitforlock});
}


sub vxi_remote {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_remote_long ($self, $args{waitforlock});
}


sub vxi_trigger {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_trigger_long ($self, $args{waitforlock});
}


sub vxi_lock {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_lock_long ($self, $args{waitforlock});
}


sub vxi_open {
        my %args = (
		address => '127.0.0.1',
		device => 0,
		@_
        );
        return vxi_open_long ($args{address}, $args{device});
}


sub vxi_write {
	my $self = shift;
	my $data = shift;
	my %args = (
		len => -1,
		waitforlock => 0,
		end => 1,
		@_
	);
	return vxi_write_long($self, $data, $args{len}, $args{waitforlock}, $args{end});
}


sub vxi_read {
	my $self = shift;
	my %args = (
                bufferlen => 1024,
                waitforlock => 0,
                termchrset => 0,
		termchr => 0,
		autochomp => 1,
                @_
        );

	my ($bytes, $string, $reason) = vxi_read_long($self, $args{bufferlen}, $args{waitforlock}, $args{termchrset},$args{termchr});

	if (defined($string) && $args{autochomp}) {
		chomp ($string);
	}
	
	return ($bytes, $string, $reason);
}


sub vxi_readstatusbyte {
        my $self = shift;
        my %args = (
                waitforlock => 0,
                @_
        );
        return vxi_readstatusbyte_long ($self, $args{waitforlock});
}


sub vxi_docmd {
        my $self = shift;
        my $cmd = shift;
	my %args = (
                datain => "",
		datainlen => -1,
		dataoutbufferlen => 256,
                waitforlock => 0,
		autochomp => 1,
                @_
        );

        my ($ret, $dataout, $dataoutlen) = vxi_docmd_long($self, $args{datain}, $args{datainlen}, $args{dataoutbufferlen}, $args{waitforlock});

        if (defined($dataout) && $args{autochomp}) {
                chomp ($dataout);
        }

        return ($ret, $dataout);
}

1;
__END__

=head1 NAME

VXI11::Client - Perl module for interfacing with VXI-11 networked test and measurement equipment

=head1 SYNOPSIS

  use VXI11::Client;

  vxi_startinterruptserver();

  my $instr = vxi_open(address => "192.168.0.62");

  $instr->vxi_lock();
  $instr->vxi_write("*idn?");
  my ($bytes, $buff, $reason) = $instr->vxi_read();
  print "got " . $bytes . ";" . $buff . " reason " . $reason ."\n";

  my ($error, $statusbyte) = $instr->vxi_readstatusbyte();
  print "status byte is " . $statusbyte . "\n";

  $instr->vxi_create_intr_chan();
  $instr->vxi_enable_srq("myhandle");
  vxi_wait_for_interrupt();
  $instr->vxi_disable_srq();
  $instr->vxi_destroy_intr_chan();
  $instr->vxi_abort();
  $instr->vxi_clear();
  $instr->vxi_trigger();
  $instr->vxi_local();
  $instr->vxi_remote();
  $instr->vxi_unlock();

  $instr->vxi_close();

  vxi_stopinterruptserver();


=head1 DESCRIPTION

A client for VXI-11 networked instruments. To start talking to an instrument
call open with the host you want to connect to (ip or hostname) and whether
you want to lock it right away. You can then call the object methods to 
do stuff. For interrupts to work you must call vxi_startinterruptserver before
enabling interrupts. You only need to do this once even if you have multiple
instruments. VXI-11 has mixed client and server roles (with interrupts the client
becomes the server). Starting the interrupt server creates an RPC server on the 
client that the instruments can connect to.

=head2 USAGE
  
INT vxi_startinterruptserver();

	Start the local RPC service for the instrument to connect to and deliver
	interrupt/service requests to.
	Make sure you have portmapper or rpcbind running and you aren't blocking
	the ports it allocates.

INT vxi_stopinterruptserver();

	Shutdown the local RPC server.

INT INST = vxi_open( address => STRING, [device => STRING] );

	Open a link to an instrument. Use the returned instance to call 
	the object methods below.

INT INST->vxi_close();

	Destroy the link to the insturment and destroy the local RPC client.
	You must not use an instance created with vxi_open(); after calling this.

INT INST->vxi_lock([waitforlock => 'false'])

	Lock the instrument. You can tell the instrument to try to wait for 
	the lock to become free and lock it via waitforlock,

INT INST->vxi_unlock();

	Unlock the instrument. Only makes sense if you are holding the lock.
              
INT INST->vxi_write(STRING data, [ len => -1,
                		   waitforlock => 0,
                                   end => 1 ]);
	Write data to the instrument. If the data is a terminated string you can 
	pass -1 as the length to have it calculated for you. If the data is not 
	terminated or for some reason you only want to write part of it you need
	to provide a length. You can wait for the lock to be freed by via waitforlock.  
	       
(INT bytes, STRING string, INT reason) INST->vxi_read([ bufferlen => 1024,
                     			    waitforlock => 0,
                     			    termchrset => 0,
                     			    termchr => 0,
                     			    autochomp => 1]);

	Read some data from the instrument. The default parameters should be fine
	for most cases. If you need to read more than 1024 bytes you should pass 
	in the required buffer size via bufferlen. This function will not read more 
	than the buffer size. The number of bytes returned is what the instrument sent
	not what was copied into the buffer. So if the number of bytes returned is
	larger than bufferlen the data is truncated. If autochomp is set the newline
	from the returned data will be automatically removed.

(INT ret, STRING dataout, INT dataoutlen) =  vxi_docmd (INT cmd, [ datain => "",
						datainlen => -1,
						dataoutbufferlen => 256,
						waitforlock => 0,
						autochomp => 1]);

	Send a command to the instrument possibly with some data. The rules for write apply
	to datain and the rules for read apply for dataout.

INT INST->vxi_abort();
	Abort an in-progress operation.	

INT vxi_readstatusbyte([ waitforlock => 0 ]);

	Read the instruments status byte.

INT INST->vxi_create_intr_chan();   

	Creates an interrupt channel from the instrument to this client.
	This must be called after vxi_startinterruptserver.

INT INST->vxi_enable_srq(STRING handle);

	Tell the instrument to fire interrupts/service requests to the 
	interrupt channel. Must be called after vxi_create_intr_chan().
	You should give a unique channel handle for each instrument as
	you will need this to work out which device set an interrupt/service 
	request. 

INT INST->vxi_disable_srq();

	Tell the instrument that you don't want it to send interrupts/
	service requests anymore. This does not destroy the interrupt 
	channel.

INT INST->vxi_destroy_intr_chan();

	Tell the instrument to disconnect from the interrupt service that
	is running locally. This does not shut down the interrupt service.

STRING vxi_wait_for_interrupt([INT timeout -1 : 0 : n])

	Waits for an interrupt/service request to be received from a connected 
	instrument. When an interrupt is caught the handle of the interrupt will
	be returned. If no interrupt is caught undef will be returned.
	You can pass a timeout in ms (the default is 250ms), or 0 to never block
	and only return interrupts that have already happened or -1 to block until
	an interrupt is caught (could block forever!).

INT INST->vxi_remote([waitforlock => 0]);      

	Lock out the instrument's display.

INT INST->vxi_local([waitforlock => 0]);

	Unlock the instrument's display.
	
INT INST->vxi_clear([waitforlock => 0]);

	Clear the instruments's display.

INT INST->vxi_trigger([waitforlock => 0]);

	Trigger the instrument.


Return codes work like this:

	1   - is a success
	0   - means the request failed locally, the state inside the client is
	incorrect, i.e. calling to enable interrupts before creating the channel
	or that the server couldn't be contacted
	< 0 - Any negative value is the negated VXI-11 error code from the server

The only exceptions to this are the read and write methods:

	0   - Error as above or zero bytes read/written
	> 0 - Number of bytes read/written

=head1 SAMPLE SCRIPTS

=head2 MINIMAL IDENTIFICATION SCRIPT

  #!/usr/bin/perl
  use strict;
  use warnings;
  use VXI11::Client;

  my $instr = vxi_open( address => "192.168.0.62" );
  $instr->vxi_write("*idn?");
  my ( $bytes, $idn, $reason ) = $instr->vxi_read();
  print "This instrument is: $idn\n";
  $instr->vxi_close();

=head2 INTERACTIVE CLIENT USING INTERRUPT CHANNEL

  #!/usr/bin/perl
  use strict;
  use warnings;
  use VXI11::Client;

  # This script provides a simple line-based shell for communicating with
  # a VXI-11.3 instrument. Errors and esponses to queries are signaled to
  # this script using the interrupt channel. The rpcbind/portmapper service
  # must be running on your system for this to work. If not, see the
  # sample script that does not use the interrupt channel. Tested with an
  # Avtech Electrosystems pulse generator.

  my $ip_addr = "192.168.0.62";    # IP address of the instrument,
                                   # or VXI-to-GPIB gateway device.
  my $device  = 0;                 # Only revelant if a VXI-to-GPIB
                                   # gateway is used.

  my $prompt = "\n> ";
  print "\nType your commands. Ctrl+C to exit\n" . $prompt;

  vxi_startinterruptserver();      # Launch a server to handle
                                   # interrupts from the instrument.
  my $my_interrupt_handle = "Avtech";    # Each interrupt source needs a name.

  my $instr = vxi_open( address => $ip_addr, device => $device ) or die "Could not open instrument at $ip_addr.";

  $instr->vxi_write("*ese 60");          # Flag command-related errors.
  $instr->vxi_write("*sre 48");          # Request service when a response is
                                         # available, or an error has occurred.
  $instr->vxi_create_intr_chan();        # Create interrupt channel.
  $instr->vxi_enable_srq($my_interrupt_handle);
                                         # Enable service requests on the
                                         # interrupt channel
  while (1) {

      # check for user input
      if ( defined( my $line = <STDIN> ) ) {
          $instr->vxi_write($line);
      }

      # was a message response or error reported within
      # the default timeout period of 250 ms?
      my $handle;
      if (   ( $handle = vxi_wait_for_interrupt() )
          && ( $handle eq $my_interrupt_handle ) )
      {
          my ( $error, $statusbyte ) = $instr->vxi_readstatusbyte();

          # query-response message available according to status byte
          if ( $statusbyte | 0x10 ) {
              my ( $bytes, $response, $reason ) = $instr->vxi_read();
              print $response. "\n";
          }

          # error occurred according to status byte
          if ( $statusbyte | 0x20 ) {
              my $response = "";

              # cycle through all errors in the error queue
              until ( $response =~ /No error/i ) {
                  $instr->vxi_write("syst:err?");
                  ( my $bytes, $response, my $reason ) = $instr->vxi_read();
                  if ( $response !~ /No error/i ) {
                      print "Error message: $response\n";
                  }
              }

              # clear the error reporting bits
              $instr->vxi_write("*cls");
          }
      }
      print $prompt;
  }

  # Tidy up!
  $instr->vxi_disable_srq();
  $instr->vxi_destroy_intr_chan();
  $instr->vxi_unlock();
  $instr->vxi_local();
  $instr->vxi_close();

=head1 SEE ALSO

The VXI-11.3 specifications.

=head1 AUTHOR

Dr. Michael J. Chudobiak, mjc@avtechpulse.com

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2013 by Avtech Electrosystems Ltd.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.


=cut