View source for MNet API

[[Category:MNET]]

==Introduction==

This page aims to serve as the canonical location for documenting the Moodle NETwork API (MNET API), both the XMLRPC functions and the associated code.  
<br><br>''It is a work in progress, please add to it as you discover undocumented code.''

== How to use MNET ==
This paragraph will explain you how to setup a connection between a client and a server with mnet. It will also explain where to write the functions you wanna call in the server.

=== Basic Client/Server code===
In this example  we'll ask the server which methods we can access. The system server methods 'ListMethods' is already implemented, so we will only write client code:

<Code php>
    require_once($CFG->dirroot . '/mnet/xmlrpc/client.php'); //mnet client library

    /// Setup MNET environment
        global $MNET;
        if (empty($MNET)) {
            $MNET = new mnet_environment();
            $MNET->init();
        }             
   
    /// Setup the server
        $host = $DB->get_record('mnet_host',array('id' => 4)); //we retrieve the server(host) from the 'mnet_host' table
        $mnet_peer = new mnet_peer();                          //we create a new mnet_peer (server/host)
        $mnet_peer->set_wwwroot($host->wwwroot);               //we set this mnet_peer with the host http address

    /// Connect to the remote moodle and retrieve the list of methods (synchronous transmission)
        $client = new mnet_xmlrpc_client();        //create a new client
        $client->set_method('system/listMethods'); //tell it which method we're going to call       
        $client->send($mnet_peer);                 //Call the server
        $response = $client->response;             //Receive the server response 

        var_dump($response);
</Code>

=== System methods ===
System methods are declared as available into /mnet/xmlrpc/client.php::permission_to_call(). If you add a new system method you will have to add its name to the system_methods array into this function.

A mnet server comes with few system methods which have been implemented into /mnet/xmlrpc/server.php::mnet_system()<br>
Parameters are saved into the $params array. Your first $client->add_param($param1) we'll be in $params[0] etc.

=== Specific methods ===
Most of the time you don't want to add a system method but a method for a module/service. You wanna to be this display by the "ListMethods" system method.

Let's implement a function returning "Hello World".

1. We create this function into servicefolder/services.php:
<code php>
class services extends repository {

    function static helloWorld($firstname, $surname) {
        return "Hello World" . $firstname . $surname; //note that we could return an array, 
                                                      //it would still be managed by mnet without a change anywhere else
    }

}
</code>

2. We register this function as a mnet function into the database:


3. The server needs to dispatch
in mnet/xmlrpc/server.php::mnet_server_dispatch(), we need to add:

<code php>
else if ($callstack[0] == 'servicefolder') {
        // Break out the callstack into its elements
        list($base, $plugin, $filename, $methodname) = $callstack;

        if ($filename == 'services.php') {
            $pluginclass = 'repository_' . $plugin;
            $includefile = '/repository/'.$plugin.'/repository.class.php';
            
            $response    = mnet_server_invoke_method('servicefolder/services.php', $methodname, $method, $payload, $pluginclass);
            $response = mnet_server_prepare_response($response);
            echo $response;
        } else {
            // Generate error response - unable to locate function
            exit(mnet_server_fault(7012, 'nosuchfunction'));
        }

    ////////////////////////////////////// STRICT MOD/*
    }
</code> 

4. We add the method to the "ListMethods" system method

5. We write some client code<br>
First of all test the code from the section "Client/Server" above. You should see "''servicefolder/services.php/helloworld''" function into the response.

We can now call this method. Change:
<code php>
    $client->set_method('system/listMethods');
</code>
For:
<code php>
    $client->set_method('servicefolder/services.php/helloworld');
    $client->add_param('Thierry'); 
    $client->add_param('Henry'); 
</code>

==Entry points/XMLRPC documentation==

The entry point is wwwroot/xmlrpc/server.php, which at some point calls mnet_permit_rpc_call, which sets some member variables in the MNET_REMOTE_CLIENT object (mnet/remote_client.php) so that later when mnet_server_dummy_method is called, it can dispatch the call accordingly.  I '''think''' mnet_server_dummy_method is the only way functions get called.

Currently you can call class methods, static methods and functions.  However, for a class method, there is currently only support to construct the object with no constructor arguments.

==Authentication Functions==

Documentation TODO

==Enrolment Functions==

Documentation TODO

== Repository Functions ==

Documentation TODO

==Portfolio Functions==

===send_content_intent===

* Defined in: portfolio/type/mahara/lib.php
* Implemented in: Mahara.  Moodle has this function but it is not an xmlrpc function, only a helper function to call the xmlrpc function in Mahara.  (See MDL-16269)
* Parameters: 
** username: username of user to find or create
* Returns: Stdclass object with keys:
** sendtype: string - either 'queue' or 'immediate' depending on what the remote system has decided
** token: string - to use for all further communication

===send_content_ready===

* Defined in: portfolio/type/mahara/lib.php
* Implemented in: Mahara.  Moodle has this function but it is not an xmlrpc function, only a helper function to call the xmlrpc function in Mahara.  (See MDL-16269)
* Parameters:
** token: string, previously return from from send_content_intent
** username: string, username of user to find
** format: string: currently just 'file', could be more later 
** data: keyed array, information '''per format'''
*** shared keys, expected by all formats:
****  totalsize: total filesize of included files (in bytes) - used for quota checks
*** 'file' format keys:
**** filesmanifest: keyed array of file information (keyed by filename):
***** filename: desired name of file
***** sha1: sha1 of file
***** size: size of file (in bytes)
**** zipfilesha1: sha1 of the zipfile containing the file(s)
**** zipfilesize: size of the zipfile containing the file(s)
** wait: boolean. whether the remote system is expected to immediately launch a request to fetch file or queue it for cron.
* Returns: Stdclass object with keys:
** status: boolean, success or failure
** type: string, 'queued' or 'complete'

===fetch_file===

* Defined in: portfolio/type/mahara/lib.php
* Implemented in: Moodle.
* Parameters:
** token: string, same that was returned in send_content_intent and used subsequently in send_content_ready
* Returns: base64 encoded file (currently a zipfile, as can include multiple files)