The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebSocket-v0.1.4
River stage zero No dependents
2 ++
/ WebSocket::Client

NAME

WebSocket::Client - WebSocket Client

SYNOPSIS

    use WebSocket::Client;
    my $uri = "ws://localhost:8080?csrf=token";
    my $ws  = WebSocket::Client->new( $uri,
    {
        on_binary     => \&on_binary,
        on_connect    => \&on_connect,
        on_disconnect => \&on_disconnect,
        on_error      => \&on_error,
        on_utf8       => \&on_message,
        on_recv       => \&on_recv,
        on_send       => \&on_send,
        origin        => 'http://localhost',
        debug         => 3,
    }) || die( WebSocket::Client->error );
    $ws->start() || die( $ws->error );

    my $stdin = AnyEvent::Handle->new(
        fh      => \*STDIN,
        on_read => sub
        {
            my $handle = shift( @_ );
            my $buf = delete( $handle->{rbuf} );
            $ws->send_utf8( $buf );
        },
        on_eof => sub
        {
            $ws->disconnect;
        }
    );

VERSION

    v0.1.0

DESCRIPTION

This is the WebSocket client class. It contains all the methods and api to connect to a remote WebSocket server and interact with it.

CONSTRUCTOR

new

The constructor takes an uri and the following options. If an uri is not provided as a first argument, it can be provided as a uri parameter; see below:

compression_threshold

See "compression_threshold"

A Cookie http field header value. It must be properly formatted.

extensions

Optional. One or more extension enabled for this client. For example permessage-deflate to enable message compression.

You can set this to either a string or a WebSocket::Extension object if you want, for example to set the extension parameters.

See rfc6455 section 9.1 for more information on extension.

Seel also "compression_threshold".

max_fragments_amount
max_payload_size
on_binary

A code reference that will be triggered upon a binary message received from the server.

See "on_binary"

on_connect

A code reference that will be triggered upon successful connection to the remote WebSocket server.

See "on_connect"

on_disconnect

A code reference that will be triggered upon the closing of the connection with the server.

See "on_disconnect"

on_error

A code reference that will be triggered whenever an error is encountered.

See "on_error"

on_handshake

A code reference that will be triggered just before the handshake procedure is completed.

Be careful, the code reference must return true upon success, or else, it will trigger a handshake failure.

on_ping

A code reference that will be triggered when a ping is issued.

See "on_ping"

on_recv

A code reference that will be triggered whenever some text or binary payload data is received from the server.

on_send

A code reference that will be triggered whenever data is sent to the remote WebSocket server.

See "on_send"

on_utf8

A code reference that will be triggered whenever text message is sent to the remote WebSocket server.

See "on_utf8"

origin

The origin of the request. See rfc6455 section on opening handshake

subprotocol

An array reference of protocols. They can be arbitrary identifiers and they are optionals.

See rfc6455 section on subprotocol

This can be changed later with "subprotocol"

uri

The uri for the remote WebSocket server.

version

The version of the WebSocket protocol. For example: draft-ietf-hybi-17

METHODS

compression_threshold

Inherited from WebSocket

Set or get the threshold in bytes above which the ut8 or binary messages will be compressed if the client and the server support compression and it is activated as an extension.

connect

Initiate the handshake with the server and return the current object.

Before returning, this method will fork a separate process to listen to incoming messages in the background, so as to be non-blocking and return control to the caller.

    my $client = WebSocket::Client->new( 'wss://chat.example.org' )->connect ||
        die( WebSocket::Client->error );
    # Listener process runs now in the background
    $client->send( 'Hello !' );

cookie

Set or get the Cookie header value.

disconnect

Close the connection with the server, and return the current object.

disconnected

Set or get a boolean value representing the connection status to the remote server socket.

There are 2 status: disconnecting and disconnected. The former is set when the client has issued a disconnection message to the remote server and is waiting for the server to acknowledge it, as per the WebSocket protocol, and the latter is set when the connection is effectively shut down.

disconnecting

Set or get the boolean value indicating the state of connection to the remote server socket.

This is set to a true value when the client has issued a disconnection notification to the server and is awaiting a response from the server, as per the rfc6455 protocol

frame_buffer

Set or get the frame buffer object.

handshake

Set or get the handshake object

ip

Set or get the ip of the remote server. This is set once a connection is established.

listen

This method is called by "connect" to listen to incoming message from the server. It is actually called twice. Once during the handshake and once the handshake is completed, the client forks a separate process in which it calls this method to listen to incoming messages.

max_fragments_amount

Takes an integer and set or get the maximum fragments amount.

max_payload_size

Takes an integer and set or get the maximum payload size.

on

Provided with an array or array reference of event name and core reference pairs and this will set those event handlers.

It returns the current object.

on_binary

Event handler triggered when a binary message is received.

The current client object and the binary message are passed as argument to the event handler.

on_connect

Event handler triggered when the connection with the server has been made and handshake performed.

The current client object is passed as argument to the event handler.

on_disconnect

Event handler triggered when the connection with the server is closed.

The current client object is passed as argument to the event handler.

on_error

Event handler triggered whenever an error occurs.

The current client object and the error message are passed as argument to the event handler.

on_handshake

Event handler triggered just before the handshake sequence is completed.

Be careful that this must return a true value, or else, it will fail the handshake.

The current client object is passed as argument to the event handler.

on_ping

Event handler triggered whenever a ping is issued to the server.

The current client object is passed as argument to the event handler.

on_recv

Event handler triggered whenever a binary or text payload is received from the server.

The current frame object and the payload data are passed as arguments to the event handler.

    $ws->on_recv(sub
    {
        my( $frame, $payload ) = @_;
        if( $frame->is_binary )
        {
            # do something
        }
        elsif( $frame->is_text )
        {
            # do something else
        }
    });

on_send

Event handler triggered whenever a message is sent to the remote server.

The current client object and the message are passed as argument to the event handler.

on_utf8

Event handler triggered whenever a text message is sent to the remote server.

The current client object and the message are passed as argument to the event handler.

origin

Set or get the origin of the request as a Module::Generic::Scalar object.

recv

Will attempt to read data from the server socket and call all relevant event handlers. It returns the current object.

send

Sends data to the server socket and returns the current object. This will also trigger associated event handlers.

Returns the current object.

send_binary

Sends binary data to the server socket and returns the current object. This will also trigger associated event handlers.

Returns the current object.

send_utf8

Sends data to the server socket after having encoded them using "encode" in Encode> and returns the current object. This will also trigger associated event handlers.

Returns the current object.

start

Start listening for possible events on the server socket.

Returns the current object.

subprotocol

Set or get an array object of WebSocket protocols and set the WebSocket header Sec-WebSocket-Protocol.

Returns a Module::Generic::Array object.

See rfc6455 for more information

shutdown

Shut down the socket by sending a "shutdown" in IO::Socket command and sets the "disconnected" status to true.

Returns the current object.

socket

Set or get the remote server socket. This expects the object to be a IO::Socket instance, or an inheriting package.

timeout

Set or get the timeout used when issuing messages to the remote server, such as close and waiting for the server response.

uri

Returns the uri of the server uri.

See rfc6455 specification

version

The WebSocket protocol version being used, such as draft-ietf-hybi-17

See rfc6455 about suport for multiple versions

CREDITS

Graham Ollis for AnyEvent::WebSocket::Client, Eric Wastl for Net::WebSocket::Server, Vyacheslav Tikhanovsky aka VTI for Protocol::WebSocket

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

WebSocket::Server, rfc6455

COPYRIGHT & LICENSE

Copyright(c) 2021 DEGUEST Pte. Ltd. DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.