ExternalServicePOSTInterface

From SynchroEdit

(Difference between revisions)
Jump to: navigation, search
Revision as of 16:45, 31 October 2006 (edit)
Kalle Alm (Talk | contribs)

← Previous diff
Revision as of 17:42, 1 December 2006 (edit)
Kalle Alm (Talk | contribs)

Next diff →
Line 36: Line 36:
* on-demand-email * on-demand-email
* promote-moderator * promote-moderator
 +* save-document
* terminate-action * terminate-action
* unban-user * unban-user
-Note that, at the point of writing, the initiate-action and may-cancel hooks are unimplemented.+Note that, at the point of writing, the initiate-action and save-document hooks are unimplemented.
Line 129: Line 130:
$actor The administrator. $actor The administrator.
$target The moderator-hopeful. $target The moderator-hopeful.
 +
 +
 +==== save-document ====
 +
 +'''save-document''' is triggered when a user -- any user -- hits Ctrl+S or in any other way requests that the document is saved. This trigger often act as a complement (identical in service) to the terminate-action trigger.
 +
 +Arguments passed:
 + $document The name of the document (e.g. "The Plan")
 + $content The XHTML content of the current session
 + $users A comma-separated list of all participants.
 + $chat The chat history in the format "user\nmessage\nuser\nmessage\n..."
 + $startstamp The timestamp when the session began.

Revision as of 17:42, 1 December 2006

Contents

External Service POST Interface (ESPI)

ESPI is kind of a bridge between SynchroEdit (the server) and the outside world, in terms of things like authentication and services that SynchroEdit does not handle itself (emailing users, for example).

ESPI is kind of meant to be a complete list of hooks which can be "attached to" via e.g. PHP or Perl, and then populated with content that integrates SynchroEdit with another service, such as a web site.

Using

Using the ESPI is (supposed to be) simple and straightforward. In the PHP implementation (the only one available right now; we are planning at least a Perl implementation also), there is a "espi_configuration.php" file and a "espi.php" file that you can put anywhere you want (but both have to be in the same location or available via PHP's PATH). The espi_configuration file is then modified by simply adding a PHP script to a by-default-empty string. For example, if you want to do something when a SynchroEdit session is shut down, you can edit espi_configuration.php and change

$ESPI_HOOKS["terminate-action"] = "";

to

$ESPI_HOOKS["terminate-action"] = "my-hooks/terminate.php";

In the synchroedit.rc file, you also specify 1) where the espi.php file you want to use is located, and 2) which hooks you want it to capture. Since it's rather wasteful to connect to the espi.php interface for every available hook if you only use one or two, you need to specify which ones to use. In synchroedit.rc, you will thus modify the lines that begin with

#ESPI = ...

and

#ESPIHooks = ...

to something like this:

ESPI = http://localhost/someplace/espi.php

and

ESPIHooks = on-terminate-action

If you want to listen to more than one hook, you simply list the hooks comma-separated on the same line. Please note that, by default, the ESPI interface will refuse connections from anywhere other than localhost. You can add one other IP address from which the ESPI accept connections in the espi_configuration.php file.

In your "my-hooks/terminate.php" file, then, you will have the appropriate variables available to you. Details below.


Available hooks

The following hooks are available:

  • authenticate-user
  • ban-user
  • demote-user
  • initiate-action
  • may-cancel
  • on-demand-email
  • promote-moderator
  • save-document
  • terminate-action
  • unban-user

Note that, at the point of writing, the initiate-action and save-document hooks are unimplemented.


Hook details

authenticate-user

authenticate-user is triggered when a user attempts to log into SynchroEdit and the server has the sessionAuthentication directive enabled. The hook handler must echo one of the following, or the user will be told that their session is invalid:

 ACCESS DENIED
 ACCESS GRANTED

Furthermore, when granting a user access, a third word may optionally be included, specifying that user's role. The available roles are GAGGED, BANNED, MODERATOR, ADMIN. For example:

 ACCESS GRANTED GAGGED
 ACCESS GRANTED BANNED
 ACCESS GRANTED MODERATOR
 ACCESS GRANTED ADMIN

(And aye, you may grant a banned user access. SynchroEdit will refuse the user access and will blame it on them being banned. ACCESS DENIED for a banned user is, thus, an invalid response as it informs the user that their session is invalid which is not the case.)

Arguments passed:

 $uid   The username.
 $pwd   The session identifier. It is referred to as password as this is consistently the
        internal reference used.
 $ip    The user's IP number, which may be used to ensure that a user on a session is
        not pretending to be somebody else.


ban-user

ban-user is triggered when a moderator or administrator has requested that a user is banned from the system. The hook handler must echo one of the following or the client will presume that the admin/moderator acted outside of their jurisdiction:

 ACCEPTED
 DECLINED

Arguments passed:

 $document   The name of the document.
 $SID        The session identifier for the document.
 $actor      The actor's username (the one executing the ban).
 $target     The target's uername (the one being banned).
 $reason     The string reason why the user is being banned.
 $time       The time in minutes that the user is being banned.


demote-user

demote-user is triggered when an administrator has requested that a moderator is turned into a regular user (i.e. demoted). The hook handler must echo ACCEPTED or DECLINED.

Arguments passed:

 $document   The name of the document in which moderator access is granted.
 $SID        The session ID for the document.
 $actor      The administrator.
 $target     The moderator-hopeful.


initiate-action

initiate-action is triggered right after the session has been initiated. [this hook is not implemented]


may-cancel

may-cancel is triggered when a user requests that the document session is canceled, shutdown, and the terminate-action ESPI hook (if any) is ignored. The default response for may-cancel (i.e. if no such hook is defined) is "decline", which means canceling the session is only possible if such a hook has been set. The hook handler must echo ACCEPTED or DECLINED. If it echoes ACCEPTED, it is akin to shutting the document down and tossing the changes out the window (which means: only let trusted users do this!).

Arguments passed:

 $document   The name of the document (e.g. "The Plan")
 $SID        The session ID for the document.
 $uid        The username for the user requesting the session is thrown away.


on-demand-email

on-demand-email is triggered when a user clicks the little envelope icon in the client, which triggers the request to email the user with the current document.

Arguments passed:

 $document   The name of the document (e.g. "The Plan")
 $content    The XHTML content of the current session
 $users      A comma-separated list of all participants.
 $chat       The chat history in the format "user\nmessage\nuser\nmessage\n..."
 $startstamp The timestamp when the session began.
 $uid        The username for the user requesting an email is sent to them.
 $email      The email address for the user in question. (Only set if emailAuthentication is used.)


promote-moderator

promote-moderator is triggered when an administrator has requested that a user is turned into a moderator. Note that this is handled almost exclusively on external level; the authenticate-user hook is used to tell what a user is and the promote-moderator/demote-user hooks are used to modify the aforementioned. This can of course also be modified outside of the context, as the roles are defined by the hooks. The hook handler must echo ACCEPTED or DECLINED.

Arguments passed:

 $document   The name of the document in which moderator access is granted.
 $SID        The session ID for the document.
 $actor      The administrator.
 $target     The moderator-hopeful.


save-document

save-document is triggered when a user -- any user -- hits Ctrl+S or in any other way requests that the document is saved. This trigger often act as a complement (identical in service) to the terminate-action trigger.

Arguments passed:

 $document   The name of the document (e.g. "The Plan")
 $content    The XHTML content of the current session
 $users      A comma-separated list of all participants.
 $chat       The chat history in the format "user\nmessage\nuser\nmessage\n..."
 $startstamp The timestamp when the session began.


terminate-action

terminate-action is triggered when a session is being shut down, right before it is unloaded from memory. For example when users are supposed to have the document emailed to them, this hook would handle that. This is fairly similar to on-demand-email above, in terms of arguments passed.

Arguments passed:

 $document   The name of the document (e.g. "The Plan")
 $content    The XHTML content of the current session
 $users      A comma-separated list of all participants.
 $chat       The chat history in the format "user\nmessage\nuser\nmessage\n..."
 $startstamp The timestamp when the session began.


unban-user

unban-user is triggered when a moderator or administrator has requested that a user ban is lifted. The hook handler must echo one of the following or the client will presume that the admin/moderator acted outside of their jurisdiction:

 ACCEPTED
 DECLINED

Arguments passed:

 $document   The name of the document.
 $SID        The session identifier for the document.
 $actor      The actor's username (the one lifting the ban).
 $target     The target's uername (the one being unbanned).
Personal tools