NAME
Net::Async::Matrix - use Matrix with IO::Async
SYNOPSIS
use Net::Async::Matrix;
use IO::Async::Loop;
my $loop = IO::Async::Loop->new;
my $matrix = Net::Async::Matrix->new(
server => "my.home.server",
);
$loop->add( $matrix );
$matrix->login(
user_id => '@my-user:home.server',
password => 'SeKr1t',
)->get;
DESCRIPTION
Matrix is an new open standard for interoperable Instant Messaging and
VoIP, providing pragmatic HTTP APIs and open source reference
implementations for creating and running your own real-time
communication infrastructure.
This module allows an program to interact with a Matrix homeserver as a
connected user client.
http://matrix.org/
EVENTS
The following events are invoked, either using subclass methods or CODE
references in parameters:
on_log $message
A request to write a debugging log message. This is provided
temporarily for development and debugging purposes, but will at some
point be removed when the code has reached a certain level of
stability.
on_presence $user, %changes
Invoked on receipt of a user presence change event from the homeserver.
%changes will map user state field names to 2-element ARRAY references,
each containing the old and new values of that field.
on_room_new $room
Invoked when a new room first becomes known about.
Passed an instance of Net::Async::Matrix::Room.
on_room_del $room
Invoked when the user has now left a room.
on_invite $event
Invoked on receipt of a room invite. The $event will contain the plain
Matrix event as received; with at least the keys inviter and room_id.
on_unknown_event $event
Invoked on receipt of any sort of event from the event stream, that is
not recognised by any of the other code. This can be used to handle new
kinds of incoming events.
PARAMETERS
The following named parameters may be passed to new or configure. In
addition, CODE references for event handlers using the event names
listed above can also be given.
server => STRING
Hostname and port number to contact the homeserver at. Given in the
form
$hostname:$port
This string will be interpolated directly into HTTP request URLs.
SSL => BOOL
Whether to use SSL/TLS to communicate with the homeserver. Defaults
false.
SSL_* => ...
Any other parameters whose names begin SSL_ will be stored for passing
to the HTTP user agent. See IO::Socket::SSL for more detail.
path_prefix => STRING
Optional. Gives the path prefix to find the Matrix client API at.
Normally this should not need modification.
on_room_member, on_room_message => CODE
Optional. Sets default event handlers on new room objects.
enable_events => BOOL
Optional. Normally enabled, but if set to a defined-but-false value
(i.e. 0 or empty string) the event stream will be disabled. This will
cause none of the incoming event handlers to be invoked, because the
server will not be polled for events.
This may be useful in simple send-only cases where the client has no
interest in receiveing any events, and wishes to reduce the load on the
homeserver.
longpoll_timeout => NUM
Optional. Timeout in seconds for the /events longpoll operation.
Defaults to 30 seconds if not supplied.
first_sync_limit => NUM
Optional. Number of events per room to fetch on the first /sync request
on startup. Defaults to the server's builtin value if not defined,
which is likely to be 10.
METHODS
The following methods documented with a trailing call to ->get return
Future instances.
login
$matrix->login( %params )->get
Performs the necessary steps required to authenticate with the
configured Home Server, actually obtain an access token and starting
the event stream (unless disabled by the enable_events option being
false). The returned Future will eventually yield the $matrix object
itself, so it can be easily chained.
There are various methods of logging in supported by Matrix; the
following sets of arguments determine which is used:
user_id, password
Log in via the m.login.password method.
user_id, access_token
Directly sets the user_id and access_token fields, bypassing the
usual login semantics. This presumes you already have an existing
access token to re-use, obtained by some other mechanism. This exists
largely for testing purposes.
register
$matrix->register( %params )->get
Performs the necessary steps required to create a new account on the
configured Home Server.
sync
$matrix->sync( %params )->get
Performs a single /sync request on the server, returning the raw
results directly.
Takes the following named parameters
since => STRING
Optional. Sync token from the previous request.
start
$f = $matrix->start
Performs the initial sync on the server, and starts the event stream to
begin receiving events.
While this method does return a Future it is not required that the
caller keep track of this; the object itself will store it. It will
complete when the initial sync has fininshed, and the event stream has
started.
If the initial sync has already been requested, this method simply
returns the future it returned the last time, ensuring that you can
await the client starting up simply by calling it; it will not start a
second time.
stop
$matrix->stop
Stops the event stream. After calling this you will need to use start
again to continue receiving events.
myself
$user = $matrix->myself
Returns the user object representing the connected user.
user
$user = $matrix->user( $user_id )
Returns the user object representing a user of the given ID, if
defined, or undef.
get_displayname
set_displayname
$name = $matrix->get_displayname->get
$matrix->set_displayname( $name )->get
Accessor and mutator for the user account's "display name" profile
field.
get_presence
set_presence
( $presence, $msg ) = $matrix->get_presence->get
$matrix->set_presence( $presence, $msg )->get
Accessor and mutator for the user's current presence state and optional
status message string.
create_room
( $room, $room_alias ) = $matrix->create_room( $alias_localpart )->get
Requests the creation of a new room and associates a new alias with the
given localpart on the server. The returned Future will return an
instance of Net::Async::Matrix::Room and a string containing the full
alias that was created.
join_room
$room = $matrix->join_room( $room_alias_or_id )->get
Requests to join an existing room with the given alias name or plain
room ID. If this room is already known by the $matrix object, this
method simply returns it.
add_alias
delete_alias
$matrix->add_alias( $alias, $room_id )->get
$matrix->delete_alias( $alias )->get
Performs a directory server request to create the given room alias
name, to point at the room ID, or to remove it again.
Note that this is likely only to be supported for alias names scoped
within the homeserver the client is connected to, and that additionally
some form of permissions system may be in effect on the server to limit
access to the directory server.
upload
$content_uri = $matrix->upload( %params )->get
Performs a post to the server's media content repository, to upload a
new piece of content, returning the content URI that points to it.
The content can be specified in any of three ways, with the following
three mutually-exclusive arguments:
content => STRING
Gives the content directly as an immediate scalar value.
file => STRING
Gives the path to a readable file on the filesystem containing the
content.
fh => IO
Gives an opened IO handle the content can be read from.
The following additional arguments are also recognised:
content_type => STRING
Gives the MIME type of the content data.
content_length => INT
Optional. If the content is being delivered from an opened filehandle
(via the fh argument), this gives the total length in bytes. This is
required in cases such as reading from pipes, when the length of the
content isn't immediately available such as by stat()ing the
filehandle.
convert_mxc_url
$url = $matrix->convert_mxc_url( $mxc )
Given a plain string or URI instance containing a Matrix media URL (in
the mxc: scheme), returns an http: or https: URL in the form of an URI
instance pointing at the media repository on the user's local
homeserver where it can be downloaded from.
USER STRUCTURES
Parameters documented as $user receive a user struct, which supports
the following methods:
$user_id = $user->user_id
User ID of the user.
$displayname = $user->displayname
Profile displayname of the user.
$presence = $user->presence
Presence state. One of offline, unavailable or online.
$last_active = $user->last_active
Epoch time that the user was last active.
SUBCLASSING METHODS
The following methods are not normally required by users of this class,
but are provided for the convenience of subclasses to override.
$room = $matrix->make_room( %params )
Returns a new instance of Net::Async::Matrix::Room.
SEE ALSO
* http://matrix.org/ - matrix.org home page
* https://github.com/matrix-org - matrix.org on github
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>