NAME POE::Component::Client::SOCKS - SOCKS enable any POE Component SYNOPSIS DESCRIPTION POE::Component::Client::SOCKS provides SOCKSification services to other POE sessions and components. It accepts connection requests and deals with all the SOCKS negotiation on your behalf. It returns either a SuccessEvent which will have a shiny socket handle for you to use or an FailureEvent which should say what went wrong. SOCKS 4 and 4a based servers are supported. CONSTRUCTORS One may start POE::Component::Client::SOCKS in two ways. If you spawn it creates a session that can then broker lots of SOCKS connections on your behalf. Or you may use 'connect' and 'bind' to broker one connection instance. POE::Component::Client::SOCKS->spawn( ... ); POE::Component::Client::SOCKS->connect( ... ); POE::Component::Client::SOCKS->bind( ... ); spawn Creates a new POE::Component::Client::SOCKS session that may be used lots of times. Takes the following optional parameters: 'alias', set an alias that you can use to address the component later; 'options', a hashref of POE session options; Returns an object. connect Creates a one-shot POE::Component::Client::SOCKS session that will connect to a SOCKS server and negotiate a CONNECT. Takes the following parameters ( mandatory ones are indicated ): 'SocksProxy', the SOCKS server that you want to connect to (Mandatory); 'RemoteAddress', the address that you want the SOCKS proxy to connect to (Mandatory); 'RemotePort', the port that you want the SOCKS proxy to connect to (Mandatory); 'SuccessEvent', the event that will be sent when a CONNECT is successful (Mandatory); 'FailureEvent', the event to send when a CONNECT is not successful or errored (Mandatory); 'SocksPort', the SOCKS server port to connect to (default is 1080); Takes any number of arbitary parameters that will passed through to the SuccessEvent/FailureEvent. Please use underscore prefixes to avoid future API changes. bind Creates a one-shot POE::Component::Client::SOCKS session that will connect to a SOCKS server and negotiate a BIND. Takes the following parameters ( mandatory ones are indicated ): 'SocksProxy', the SOCKS server that you want to connect to (Mandatory); 'RemoteAddress', the address that you want the SOCKS proxy to connect to (Mandatory); 'RemotePort', the port that you want the SOCKS proxy to connect to (Mandatory); 'SuccessEvent', the event that will be sent when a BIND is successful (Mandatory); 'FailureEvent', the event to send when a BIND is not successful or errored (Mandatory); 'SocksPort', the SOCKS server port to connect to (default is 1080); Takes any number of arbitary parameters that will passed through to the SuccessEvent/FailureEvent. Please use underscore prefixes to avoid future API changes. METHODS connect Connect to a SOCKS server and negotiate a CONNECT. Takes the following parameters ( mandatory ones are indicated ): 'SocksProxy', the SOCKS server that you want to connect to (Mandatory); 'RemoteAddress', the address that you want the SOCKS proxy to connect to (Mandatory); 'RemotePort', the port that you want the SOCKS proxy to connect to (Mandatory); 'SuccessEvent', the event that will be sent when a CONNECT is successful (Mandatory); 'FailureEvent', the event to send when a CONNECT is not successful or errored (Mandatory); 'SocksPort', the SOCKS server port to connect to (default is 1080); Takes any number of arbitary parameters that will passed through to the SuccessEvent/FailureEvent. Please use underscore prefixes to avoid future API changes. bind Connect to a SOCKS server and negotiate a BIND. Takes the following parameters ( mandatory ones are indicated ): 'SocksProxy', the SOCKS server that you want to connect to (Mandatory); 'RemoteAddress', the address that you want the SOCKS proxy to connect to (Mandatory); 'RemotePort', the port that you want the SOCKS proxy to connect to (Mandatory); 'SuccessEvent', the event that will be sent when a BIND is successful (Mandatory); 'FailureEvent', the event to send when a BIND is not successful or errored (Mandatory); 'SocksPort', the SOCKS server port to connect to (default is 1080); Takes any number of arbitary parameters that will passed through to the SuccessEvent/FailureEvent. Please use underscore prefixes to avoid future API changes. shutdown Terminates the component. Disconnects any pending SOCKS requests. session_id INPUT EVENTS connect Connect to a SOCKS server and negotiate a CONNECT. Takes the following parameters ( mandatory ones are indicated ): 'SocksProxy', the SOCKS server that you want to connect to (Mandatory); 'RemoteAddress', the address that you want the SOCKS proxy to connect to (Mandatory); 'RemotePort', the port that you want the SOCKS proxy to connect to (Mandatory); 'SuccessEvent', the event that will be sent when a CONNECT is successful (Mandatory); 'FailureEvent', the event to send when a CONNECT is not successful or errored (Mandatory); 'SocksPort', the SOCKS server port to connect to (default is 1080); Takes any number of arbitary parameters that will passed through to the SuccessEvent/FailureEvent. Please use underscore prefixes to avoid future API changes. bind Connect to a SOCKS server and negotiate a BIND. Takes the following parameters ( mandatory ones are indicated ): 'SocksProxy', the SOCKS server that you want to connect to (Mandatory); 'RemoteAddress', the address that you want the SOCKS proxy to connect to (Mandatory); 'RemotePort', the port that you want the SOCKS proxy to connect to (Mandatory); 'SuccessEvent', the event that will be sent when a BIND is successful (Mandatory); 'FailureEvent', the event to send when a BIND is not successful or errored (Mandatory); 'SocksPort', the SOCKS server port to connect to (default is 1080); Takes any number of arbitary parameters that will passed through to the SuccessEvent/FailureEvent. Please use underscore prefixes to avoid future API changes. shutdown Terminates the component. Disconnects any pending SOCKS requests. OUTPUT EVENTS The component returns either a SuccessEvent or an FailureEvent, you specify the events in your session that you wish to be triggered for each type. ARG0 will be a hashref. See details following. Any arbitary parameters passed though will be in the returned hashref. SuccessEvent All the parameters passed to 'connect' or 'bind' will be present, plus: 'socket', the socket handle of the connection to the SOCKS server; 'socks_response', an arrayref consisting of the reply from the SOCKS server: the result code, the dest IP and the dest port. For a BIND, the dest IP and the dest port are the address and port that the SOCKS server has opened for listening. FailureEvent Generated if something went wrong, either a connection could not be established with the SOCKS server or the SOCKS server rejected our request. If a connection to the SOCKS server could not be established then the following will exist: 'sockerr', an arrayref containing the operation, errnum and errstr as returned by POE::Wheel::SocketFactory; If the SOCKS server rejected our request for some reason the following will exist: 'socks_unknown', a string error message. This is generated if we get a garbled response from the SOCKS server; 'socks_error', an integer response from the SOCKS server, indicating that it has rejected the request. AUTHOR Chris 'BinGOs' Williams SEE ALSO POE::Wheel::SocketFactory