Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

MNet API

From MoodleDocs


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.

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:

   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);

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()
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: 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
   }

}

2. We register this function as a mnet function into the database:
Into admin/mnet/adminlib.php::upgrade_RPC_functions(), we add this case at the end: TODO /* else if ('repository' == $type) {

$docname = 'services.php'; $relname = '/servicefolder/'. $docname; $filename = $CFG->dirroot . $relname; require_once($CFG->dirroot . '/servicefolder/services.php'); $publishes = (array)repository_static_function($parentname, 'mnet_publishes'); }

if ($plugins = get_list_of_plugins('services')) {
       
       foreach ($plugins as $p) {
          
           mnet_get_functions('service', $p);
       }
   }
  • /

Into servicefolder/services.php, add public static function mnet_publishes() {

   $service= array();
   $service['name']        = 'service'; // Name & Description go in lang file
   $service['apiversion']  = 1;
   $service['methods']     = array('helloWorld');
   return array($service);

}

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

else if ($callstack[0] == 'servicefolder') {

       list($base, $filename, $methodname) = $callstack;  // Break out the callstack into its elements
       if ($filename == 'services.php') {   
           $response = mnet_server_invoke_method('/servicefolder/services.php', $methodname, $method, $payload, 'services');
           $response = mnet_server_prepare_response($response);
           echo $response;
       } else {
       /// Generate error response - unable to locate function
           exit(mnet_server_fault(7012, 'nosuchfunction'));
       }

}

4. We add the method to the "ListMethods" system method
No code is needed. Just go into the Moodle Administration > Networking > Peers. Select the Services tab from the host server. There, activate your service.

5. We write some client code
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: $client->set_method('system/listMethods'); For: $client->set_method('servicefolder/services.php/helloworld'); $client->add_param('Thierry'); $client->add_param('Henry');

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)