view release on metacpan or  search on metacpan

LDT.pm  view on Meta::CPAN

=head1 METHODS

=cut


# -------------------------------------------------------------------
=pod

=head2 new()

The constructor builds a new object for data transfers. All parameters
except of the class name are passed named (this means, by a hash).

B<Parameters:>

=over 4

=item Class name

the first parameter as usual - passed implicitly by Perl:

  my $asciiClient=new IPC::LDT(...);

The method form of construtor calls is not supported.

=item handle

The handle to be used to perform the communication. It has to be opened
already and will not be closed if the object will be destroyed.

 Example:
  handle => SERVER

A closed handle is I<not> accepted.

You can use whatever type of handle meets your needs. Usually it is a socket
or anything derived from a socket. For example, if you want to perform secure
IPC, the handle could be made by Net::SSL. There is only one precondition:
the handle has to provide a B<fileno()> method. (You can enorce this even for
Perls default handles by simply using B<FileHandle>.)

=item objectMode

Pass a true value if you want to transfer data structures. If this
setting is missed or a "false" value is passed, the object will transfer
strings.

Data structures will be serialized via I<Storable> for transfer. Because
of this, such a communication is usually restricted to partners which could
use I<Storable> methods as well to reconstruct the data structures (which
means that they are written in Perl).

String transfer objects, on the other hand, can be used to cimmunicate with
any partner who speaks the LDT protocol. We use Java and C clients as well
as Perl ones, for example.

 Example:
  objectMode => 1

The transfer mode may be changed while the object is alive by using the
methods I<setObjectMode()> and I<setAsciiMode()>.

=item startblockLength

sets the length of the initial info block which preceds every LDT
message coding the length of the remaining message. This setting is
done in bytes.

If no value is provided, the builtin default value I<LDT_INFO_LENGTH>
is used. (This value can be imported in your own code, see section
"I<Exports>" for details.) I<LDT_INFO_LENGTH> is designed to meet
usual needs.

 Example:
  startblockLength => 4

=item traceMode

Set this flag to a true value if you want to trace to actions of the
module. If set, messages will be displayed on STDERR reporting what
is going on.

Traces for <all> objects of this class can be activated (regardless of
this constructor parameter) via I<$IPC::LDT::Trace>. This is described
more detailed in section "I<CONSTANTS>".

 Example:
  traceMode => 1

=back

B<Return value:>

A successfull constructor call replies the new object. A failed call
replies an undefined value.

B<Examples:>

  my $asciiClient=new IPC::LDT(handle=>HANDLE);
  my $objectClient=new IPC::LDT(handle=>HANDLE, objectMode=>1);

=cut
# -------------------------------------------------------------------
sub new
 {
  # get parameters
  bug("Number of parameters should be even") unless @_ % 2;
  my ($class, %switches)=@_;

  # and check them
  bug("Missing class name parameter") unless $class;
  bug("Constructor called as method, use copy() method instead") if ref($class);
  bug("Missing handle parameter") unless exists $switches{'handle'} and $switches{'handle'};

  # declare function variables
  my ($me);

  # make new object
  {
   no strict 'refs';