/ 
POE-Wheel-UDP-0.02
River stage one • 3 direct dependents • 3 total dependents
/ POE::Wheel::UDP

NAME

POE::Wheel::UDP - POE Wheel for UDP handling.

SYNOPSIS

  use POE;
  use POE::Wheel::UDP;
  
  POE::Session->create(
    inline_states => {
      _start => sub {
        my $wheel = $_[HEAP]->{wheel} = POE::Wheel::UDP->new(
	  LocalAddr => '10.0.0.1',
	  LocalPort => 1234,
	  PeerAddr => '10.0.0.2',
	  PeerPort => 1235,
	  InputEvent => 'input',
	  Filter => POE::Filter::Stream->new,
	);
	$wheel->put(
	  {
            payload => [ 'This datagram will go to the default address.' ],
	  },
	  {
            payload => [ 'This datagram will go to the explicit address and port I have paired with it.' ],
	    addr => '10.0.0.3',
	    port => 1236,
	  },
	);
      },
      input => sub {
      	my ($wheel_id, $input) = @_[ARG0, ARG1];
	print "Incoming datagram from $input->{addr}:$input->{port}: '$input->{payload}'\n";
      },
    }
  );

  POE::Kernel->run;

DESCRIPTION

POE Wheel for UDP handling.

Package Methods

$wheel = POE::Wheel::UDP->new( OPTIONS );

Constructor for a new UDP Wheel object. OPTIONS is a key => value pair list specifying the following options:

LocalAddr
LocalPort

(Required Pair)

Specify the local IP address and port for the created socket. LocalAddr should be in dotted-quad notation, and LocalPort should be an integer. This module will not resolve names to numbers at all.

PeerAddr
PeerPort

(Optional Pair)

Specify the remote IP address and port for the created socket. As above, PeerAddr should be in dotted-quad notation, and PeerPort should be an integer. These arguments are used to perform a C connect(2) on the socket, which means that outbound datagrams will be sent to this address by default AND inbound datagrams from sources other than this peer will be ignored. If you want to just set a default destination for packets, use the DefaultAddr and DefaultPort items instead.

DefaultAddr
DefaultPort

(Optional Pair)

Dotted quad, and integer (respectively) options for the default destination of datagrams originating from this wheel. This setting will override the PeerAddr and PeerPort on each put() method, but you can override this by passing arguments directly to the put() method.

InputEvent

(Optional)

Specify the event to be invoked via Kernel->yield when a packet arrives on this socket. Currently all incoming data is truncated to 1500 bytes. If you do not specify an event, the wheel will not ask the kernel to pass incoming datagrams to it, and therefore this wheel will not hold your session alive.

InputFilter

(Required if InputEvent defined)

Assign a POE::Filter object to the input side of this wheel.

OutputFilter

(Required if you want to call the put method)

Assign a POE::Filter object to the output side of this wheel.

Filter

Shorthand for assigning the same filter object to both the InputFilter and OutputFilter arguments.

Object Methods

$wheel->put( LIST )

Returns the total number of bytes sent in this call, which may not match the number of bytes you passed in for payloads due to send(2) semantics. Takes a list of hashrefs with the following useful keys in them:

payload

An arrayref of records you wish to put through the filter and send in datagrams. The arrayref is used to allow more than one logical record per datagram.

bytes

How many bytes were read from this datagram. Currently a maximum of 1500 will be read, and datagrams which are larger will be truncated.

addr
port

Specify a destination IP address and port for this specific packet. Optional if you specified a PeerAddr and PeerPort in the wheel constructor; Required if you did not.

Events

InputEvent

ARG0

Contains a hashref with the following keys:

addr
port

Specifies the address and port from which we received this datagram.

payload

An arrayref of records built from the actual datagram going through the filters.

ARG1

The wheel id for the wheel that fired this event.

Filter semantics

Datagram filter design is not guaranteed yet, we need to make sure the design I put in place here is workable.

Upcoming features

  • IPV6 support.

  • TTL changing support.

SEE ALSO

POE

AUTHOR

Jonathan Steinert <hachi@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Jonathan Steinert... or Six Apart... I don't know who owns me when I'm at home. Oh well.

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