<?php
/*
  This code is part of FusionDirectory (http://www.fusiondirectory.org/)
  Copyright (C) 2013-2016  FusionDirectory

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
*/

/*!
 * \file jsonrpc.php.doc
 * \brief This is the webservice for FusionDirectory
 *
 * It's a JSON-RPC service usually used through HTTPS. It should be put in the html folder of FusionDirectory
 * Then the url of the webservice will be the url of your FusionDirectory instance followed by /jsonrpc.php
 */

/*!
 * \brief This class is the JSON-RPC webservice of FusionDirectory
 *
 * It must be served through jsonRPCServer::handle
 * */
class fdRPCService
{
  /*!
   * \brief Get the list of configured LDAP servers
   *
   * \return The list of configured LDAP servers as an associative array (keys are ids, values are displayable names)
   */
  function listLdaps() {}
  /*!
   * \brief Login into the webservice
   *
   * \param string $ldap the id of the LDAP server to use (can be NULL, in which case the first LDAP server found is used)
   * \param string $user The user to log in with
   * \param string $pwd The password for this user
   *
   * \return A session ID on success
   */
  function login($ldap, $user, $pwd) {}

  /*!
   * \brief Get list of object of objectType $type in $ou
   *
   * \param string  $sid the session id
   * \param string  $type the objectType to list
   * \param mixed   $attrs The attributes to fetch.
   * If this is a single value, the resulting associative array will have for each dn the value of this attribute.
   * If this is an array, the keys must be the wanted attributes, and the values can be either 1, '*' or 'raw'
   *  depending if you want a single value or an array of values. 'raw' means untouched LDAP value and is only useful for dns.
   *  Other values are considered to be 1.
   * \param string  $ou the LDAP branch to search in, base will be used if it is NULL
   * \param string  $filter an additional filter to use in the LDAP search.
   *
   * \return The list of objects as an associative array (keys are dns)
   */
  function ls ($sid, $type, $attrs = NULL, $ou = NULL, $filter = '')
  {
  }

  /*!
   * \brief Get count of objects of objectType $type in $ou
   *
   * \param string  $sid the session id
   * \param string  $type the objectType to list
   * \param string  $ou the LDAP branch to search in, base will be used if it is NULL
   * \param string  $filter an additional filter to use in the LDAP search.
   *
   * \return The number of objects of type $type in $ou
   */
  function count ($sid, $type, $ou = NULL, $filter = '')
  {
  }

  /*!
   * \brief Get information about objectType $type
   *
   * \param string  $sid the session id
   * \param string  $type the object type
   *
   * \return The information on this type as an associative array
   */
  function infos($sid, $type)
  {
  }

  /*!
   * \brief List existing object types
   *
   * \param string  $sid the session id
   *
   * \return An associative array with types as keys and their names as values
   */
  function listTypes($sid)
  {
  }

  /*!
   * \brief List tabs on an object
   *
   * \param string  $sid the session id
   * \param string  $type the object type
   * \param string  $dn   the object to load values from if any
   *
   * \return List of all tabs on the object, keys are ids, values are array with name (string) and active (boolean) keys.
   */
  function listTabs($sid, $type, $dn = NULL)
  {
  }

  /*!
   * \brief Get all form fields from an object (or an object type)
   *
   * Fields as they appear in the HTML form
   *
   * \param string  $sid  the session id
   * \param string  $type the object type
   * \param string  $dn   the object to load values from if any
   * \param string  $tab  the tab to show if not the main one
   *
   * \return All form fields organized as sections
   */
  function formfields($sid, $type, $dn = NULL, $tab = NULL)
  {
  }

  /*!
   * \brief Update form values of an object's attributes through POST
   *
   * \param string  $sid  the session id
   * \param string  $type the object type
   * \param string  $dn   the object to load values from if any (otherwise it's a creation)
   * \param string  $tab  the tab to modify if not the main one
   * \param array   $post the values as a POST array. Keys should be the 'id' returned by formfields.
   *
   * \return An array with errors if any, the resulting object dn otherwise
   */
  function formpost($sid, $type, $dn, $tab, $post)
  {
  }

  /*!
   * \brief Get all internal FD fields from an object (or an object type)
   *
   * Fields as they are stored in FusionDirectory
   *
   * \param string  $sid  the session id
   * \param string  $type the object type
   * \param string  $dn   the object to load values from if any
   * \param string  $tab  the tab to show if not the main one
   *
   * \return All FD attributes organized as sections
   */
  function getfields($sid, $type, $dn = NULL, $tab = NULL)
  {
  }

  /*!
   * \brief Update attributes values of an object
   *
   * \param string  $sid    the session id
   * \param string  $type   the object type
   * \param string  $dn     the object to load values from if any (otherwise it's a creation)
   * \param array   $values the values as an associative array of associative arrays. First level keys are tabs, second level keys should be the same keys returned by getfields (without section, directly the attributes).
   * Values should be formed as the internal attribute expects them. See the concerned attribute type for more information.
   *
   * \return An array with errors if any, the resulting object dn otherwise
   */
  function setfields($sid, $type, $dn, $values)
  {
  }

  /*!
   * \brief Get needed internal FD fields from a template
   *
   * This returns the fields that needs filling for using this template to create an object.
   * Return value looks like the getfields one, except they are grouped by tab and not by section.
   * Empty activated tab may also be included.
   *
   * \param string  $sid  the session id
   * \param string  $type the object type
   * \param string  $dn   the template dn
   *
   * \return FD attributes organized as tabs
   */
  function gettemplate($sid, $type, $dn)
  {
  }

  /*!
   * \brief Create an object from a template
   *
   * This apply the template to the given values and creates an object.
   *
   * \param string  $sid    the session id
   * \param string  $type   the object type
   * \param string  $dn     the template dn
   * \param string  $values the values for each tab organised in the same way as for setfields
   *
   * \return the created object dn upon success
   */
  function usetemplate($sid, $type, $dn, $values)
  {
  }

  /*!
   * \brief Lock or unlock a user
   *
   * \param string  $sid  the session id
   * \param string  $dns  an array of user dns to be locked, or a single dn of a user to lock
   * \param string  $type the action to be done. Can be 'lock', 'unlock' or 'toggle'. Defaults to 'toggle'.
   */
  function lockUser($sid, $dns, $type = 'toggle')
  {
  }

  /*!
   * \brief Test if a user is locked
   *
   * \param string  $sid  the session id
   * \param string  $dns  an array of user dns to test if they are locked, or a single dn of a user to test
   *
   * \return an associative array of booleans, the keys are the dns of the users
   */
  function isUserLocked($sid, $dns)
  {
  }

  /*!
   * \brief Generate recovery token for a user
   *
   * \param string  $sid    the session id
   * \param string  $email  an email address associated to the user
   *
   * \return an associative array with keys "token" and "uid" upon success
   */
  function recoveryGenToken($sid, $email)
  {
  }

  /*!
   * \brief Change a user password using a recovery token
   *
   * \param string  $sid        the session id
   * \param string  $uid        the uid of the user
   * \param string  $password1  the password entered by the user
   * \param string  $password2  the repeated password entered by the user
   * \param string  $token      the recovery token
   *
   * \return TRUE upon success
   */
  function recoveryConfirmPasswordChange($sid, $uid, $password1, $password2, $token)
  {
  }

  /*!
   * \brief Get the session ID
   *
   * \return The session ID for the current session. (Mainly useless unless you log in with HTTP auth instead of login method)
   */
  function getId ()
  {
  }

  /*!
   * \brief Get the LDAP base
   *
   * \param string  $sid the session id
   *
   * \return The configured LDAP base for the selected LDAP in this webservice session (see login)
   */
  function getBase ($sid)
  {
  }
}
?>