NAME `Net::Async::Matrix' - use Matrix with IO::Async SYNOPSIS TODO 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. 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. user_id => STRING access_token => STRING Optional login details to use for logging in as an existing user if an access token is already known. For registering a new user, see instead the `register' method. 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. METHODS The following methods documented with a trailing call to `->get' return Future instances. $f = $matrix->start Performs the initial IMSync 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 IMSync 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. $matrix->stop Stops the event stream. After calling this you will need to use `start' again to continue receiving events. $user = $matrix->myself Returns the user object representing the connected user. $user = $matrix->user( $user_id ) Returns the user object representing a user of the given ID, if defined, or `undef'. ( $user_id, $access_token ) = $matrix->register( $localpart )->get Sends a user account registration request to the Matrix homeserver to create a new account. On successful completion, the returned user ID and token are stored by the object itself and the event stream is started. $name = $matrix->get_displayname->get $matrix->set_displayname( $name )->get Accessor and mutator for the user account's "display name" profile field. ( $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. ( $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. $matrix->join_room( $room_alias_or_id )->get Requests to join an existing room with the given alias name or plain room ID. 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. SEE ALSO * http://matrix.org/ - matrix.org home page * https://github.com/matrix-org - matrix.org on github AUTHOR Paul Evans