mirror of
https://github.com/acanas/swad-core.git
synced 2024-09-23 00:00:50 +02:00
1347 lines
59 KiB
HTML
1347 lines
59 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="in" lang="in">
|
|
|
|
<head>
|
|
<title>SWAD: Plugins and web service</title>
|
|
<link rel="StyleSheet" href="/swad.css" type="text/css" />
|
|
<style type="text/css">
|
|
.WS_FUNCTION
|
|
{
|
|
font-size:24pt;
|
|
font-weight:bold;
|
|
}
|
|
.not_implemented
|
|
{
|
|
color:#A0A0A0;
|
|
}
|
|
</style>
|
|
<script>
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-40768375-1', 'openswad.org', {
|
|
'anonymizeIp': true,
|
|
'storage': 'none',
|
|
'clientId': window.localStorage.getItem('ga_clientId')
|
|
});
|
|
ga(function(tracker) {
|
|
window.localStorage.setItem('ga_clientID', tracker.get('clientId'));
|
|
});
|
|
ga('send', 'pageview');
|
|
|
|
</script>
|
|
</head>
|
|
|
|
<body>
|
|
<table width="100%" border="0" cellpadding="20" cellspacing="0">
|
|
<tr>
|
|
<td align="center">
|
|
<table width="90%" border="0" cellspacing="20">
|
|
|
|
<tr>
|
|
<td align="center" class="SWAD">
|
|
<a href="http://openswad.org/" class="SWAD"><img src="/logo/swad224x64.png" alt="SWAD" width="224" height="64" />
|
|
<br />shared workspace at a distance</a>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center">
|
|
<h1>Plugins and web service</h1>
|
|
<a href="http://creativecommons.org/licenses/by-sa/3.0/deed.es_ES"
|
|
title="License of text on this page" class="COPYRIGHT"><img src="/img/cc-by-sa.png"
|
|
style="width:88px; height=31px; vertical-align:middle;" alt="CC BY-SA" /></a>
|
|
<a href="http://www.ugr.es/~acanas/">Antonio Cañas Vargas</a>, 1999-2015
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left">
|
|
|
|
<h2>Plugins</h2>
|
|
|
|
<p align="justify">
|
|
It is possible to develop plugins for <a href="http://openswad.org/">SWAD</a>.
|
|
In this context, a <a href="http://en.wikipedia.org/wiki/Plug-in_(computing)">plugin</a>
|
|
is a program external to SWAD,
|
|
that interacts with it to provide some functions not provided by SWAD.
|
|
Currently, there is only a plugin available: the <a href="/swadroid/">SWADroid app</a>
|
|
for Android mobile devices,
|
|
and other plugins are under development.
|
|
</p>
|
|
|
|
<p align="justify">
|
|
SWAD has a form that allows administrators to add new plugins
|
|
or edit the existing plugins.
|
|
Each plugin is specified by the following elements:
|
|
</p>
|
|
<ul>
|
|
<li>Code (internal number that identifies the plugin in database).</li>
|
|
<li>Name.</li>
|
|
<li>Description.</li>
|
|
<li>Logo or icon.</li>
|
|
<li>App key.</li>
|
|
<li>URL (optional).</li>
|
|
<li>IP (optional).</li>
|
|
</ul>
|
|
|
|
<h2>Web service</h2>
|
|
|
|
<p align="justify">
|
|
The plugins interact with the program SWAD
|
|
through a web service with several operations or functions.
|
|
A <a href="http://en.wikipedia.org/wiki/Web_service">web service</a>
|
|
is a software system that allows the interaction between two computers
|
|
connected to Internet.
|
|
In our case, SWAD is the server or host that offers the web service,
|
|
and the plugin is the client that request one or several functions from the web service.
|
|
</p>
|
|
|
|
<p align="justify">
|
|
There are two possible ways to access to a SWAD plugin:
|
|
</p>
|
|
<ul>
|
|
<li><p><strong>Directly from the external application</strong>:
|
|
The user logs in directly using a form in the external application.
|
|
The external application calls SWAD by using the function
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a>.</p>
|
|
</li>
|
|
|
|
<li><p><strong>From SWAD</strong>:
|
|
The user logs in SWAD.
|
|
SWAD provides a listing of the available plugins in the option System > List of plugins.
|
|
When the user clicks on the link to a plugin,
|
|
the web address resulting of concatenate the URL of that plugin
|
|
with the identifier of the current session is used.
|
|
For example, if the URL specified in the plugin is <code>http://my.url.com/index.php?mode=session&id=</code>
|
|
and the session identifier is <code>cY_kAutNT5HzF3MbflcuXgXFlv00Wmqq9QKeD1aaaRc</code>, the following address is called:
|
|
<code>http://my.url.com/index.php?mode=session&id=cY_kAutNT5HzF3MbflcuXgXFlv00Wmqq9QKeD1aaaRc</code>.
|
|
The external application then calls SWAD using the function <a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h2>SOAP</h2>
|
|
|
|
<p align="justify">
|
|
The exchange of informationn between the SWAD web service (server) and a plugin (client)
|
|
is performed through <a href="http://en.wikipedia.org/wiki/XML">XML (Extensible Markup Language)</a> messages
|
|
using the protocol <a href="http://en.wikipedia.org/wiki/SOAP">SOAP (Simple Object Access Protocol)</a>.
|
|
The client sends a SOAP message to the server
|
|
with the operation or function that it wants to invoque and a number of parameters.
|
|
The server returns an XML document
|
|
with the resulting data (users, courses, etc.).
|
|
</p>
|
|
|
|
<p align="justify">
|
|
The main core of SWAD, <a href="/source/">written in C</a>,
|
|
uses the tool <a href="http://www.cs.fsu.edu/~engelen/soap.html">gSOAP</a>
|
|
to implement the SOAP server protocol.
|
|
The plugins can be written in any programming language,
|
|
so they will use the available libraries in that language to implement the SOAP client protocol.
|
|
</p>
|
|
|
|
<h2>WSDL</h2>
|
|
|
|
<p align="justify">
|
|
The interface of a web service is given in a format automatically processable written in
|
|
<a href="http://en.wikipedia.org/wiki/Web_Services_Description_Language">WSDL (Web Services Description Language)</a>.
|
|
The SWAD server provides to the clientes several operations or functions indicated
|
|
in the WSDL file:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><a href="http://openswad.org/ws/swad.wsdl">http://openswad.org/ws/swad.wsdl</a></li>
|
|
<li><a href="http://swad.ugr.es/ws/swad.wsdl">http://swad.ugr.es/ws/swad.wsdl</a></li>
|
|
<li><a href="http://www.cevuna.una.py/swad/ws/swad.wsdl">http://www.cevuna.una.py/swad/ws/swad.wsdl</a></li>
|
|
</ul>
|
|
|
|
<p align="justify">
|
|
At the end of the WSDL file you can find the URL to call the SWAD web service.
|
|
The CGI executed as answer detects that a call to the web service (and not a normal web request) is performed
|
|
if the variable <code>CONTENT_TYPE</code> is set to <code>text/xml</code>.
|
|
In this case, it responds to the client with the XML output of the SOAP protocol.
|
|
</p>
|
|
|
|
<h2>Operations or functions provided by this web service</h2>
|
|
|
|
<p align="justify">
|
|
The SWAD web service provides the following operations:
|
|
</p>
|
|
<ul>
|
|
<li><a href="#createAccount"><code>createAccount</code></a></li>
|
|
<li><a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a></li>
|
|
<li><a href="#loginBySessionKey"><code>loginBySessionKey</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#getNewPassword"><code>getNewPassword</code></a></li>
|
|
|
|
<li><a href="#getCourses"><code>getCourses</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#getCourseInfo"><code>getCourseInfo</code></a></li>
|
|
|
|
<li><a href="#getGroupTypes"><code>getGroupTypes</code></a></li>
|
|
<li><a href="#getGroups"><code>getGroups</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#sendMyGroups"><code>sendMyGroups</code></a></li>
|
|
|
|
<li><a href="#getDirectoryTree"><code>getDirectoryTree</code></a></li>
|
|
<li><a href="#getFile"><code>getFile</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#getMarks"><code>getMarks</code></a></li>
|
|
|
|
<li><a href="#getTestConfig"><code>getTestConfig</code></a></li>
|
|
<li><a href="#getTests"><code>getTests</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#getTrivialQuestion"><code>getTrivialQuestion</code></a></li>
|
|
|
|
<li style="margin-bottom:1em;"><a href="#getUsers"><code>getUsers</code></a></li>
|
|
|
|
<li><a href="#getAttendanceEvents"><code>getAttendanceEvents</code></a></li>
|
|
<li><a href="#sendAttendanceEvent"><code>sendAttendanceEvent</code></a></li>
|
|
<li><a href="#getAttendanceUsers"><code>getAttendanceUsers</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#sendAttendanceUsers"><code>sendAttendanceUsers</code></a></li>
|
|
|
|
<li><a href="#getNotifications"><code>getNotifications</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#markNotificationsAsRead"><code>markNotificationsAsRead</code></a></li>
|
|
|
|
<li><a href="#sendNotice"><code>sendNotice</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#sendMessage"><code>sendMessage</code></a></li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="createAccount"><h3 class="WS_FUNCTION"><code>createAccount</code></h3></a>
|
|
<p align="justify">
|
|
Create a new user account.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>userNickname</strong>: string starting by @ (@nickname of the user).</li>
|
|
<li><strong>userEmail</strong>: string (email of the user).</li>
|
|
<!-- <li><strong>userID</strong>: string (DNI/passport of the user).</li> -->
|
|
<li><strong>userPassword</strong>: string, plain password.</li>
|
|
<li><strong>appKey</strong>: string, key used by the application.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>userCode</strong>: integer, unique identifier of the user.
|
|
<ul>
|
|
<li>If <= 0, an error has happened, the account has not been created.
|
|
<ul>
|
|
<li>-1 → nickname not valid</li>
|
|
<li>-2 → nickname registered by another user</li>
|
|
<li>-3 → e-mail not valid</li>
|
|
<li>-4 → e-mail registered by another user</li>
|
|
<li>-5 → password not valid (too short, too trivial...)</li>
|
|
</ul>
|
|
</li>
|
|
<li>If > 0, the account has been successfully created
|
|
and this unique identifier has been assigned to the new user.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>wsKey</strong>: string, identifier used in the calls to other operations.
|
|
Use only when <strong>userCode</strong> > 0.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="loginByUserPasswordKey"><h3 class="WS_FUNCTION"><code>loginByUserPasswordKey</code></h3></a>
|
|
<p align="justify">
|
|
Returns data of the user, given an identifier of the user (DNI/passport, @nickname or email),
|
|
a password and an application key.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>userID</strong>: string (DNI/passport, @nickname or email of the user).</li>
|
|
<li><strong>userPassword</strong>: string, password encrypted with
|
|
the algoritthm <a href="http://en.wikipedia.org/wiki/SHA_hash_functions">SHA-512</a>
|
|
and in format <a href="http://tools.ietf.org/html/rfc4648">base64url</a>.</li>
|
|
<li><strong>appKey</strong>: string, key used by the application.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>userCode</strong>: integer, unique identifier of the user.</li>
|
|
<li><strong>wsKey</strong>: string, identifier used in the calls to other operations.</li>
|
|
<li><strong>userNickname</strong>: string, user's nickname (without @).</li>
|
|
<li><strong>userID</strong>: string, DNI/passport of the user.</li>
|
|
<li><strong>userSurname1</strong>: string.</li>
|
|
<li><strong>userSurname2</strong>: string.</li>
|
|
<li><strong>userFirstname</strong>: string.</li>
|
|
<li><strong>userPhoto</strong>: string
|
|
with the full URL of a JPG image
|
|
of size 150 (width) × 200 (height).
|
|
If it is an empty string, the user
|
|
has no photo or it can not be shown.
|
|
</li>
|
|
<li><strong>userBirthday</strong>: string, in YYYYMMDD format.</li>
|
|
<li><strong>userRole</strong>: integer, maximum role of the user,
|
|
with one of the following 4 values:
|
|
<ul>
|
|
<li><var>0</var>: unknown, an error has occurred.</li>
|
|
<li><var>1</var>: invited, not enrolled in any course.</li>
|
|
<li><var>2</var>: student in all his/her courses.</li>
|
|
<li><var>3</var>: teacher in at aleast one of his/her courses.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="loginBySessionKey"><h3 class="WS_FUNCTION"><code>loginBySessionKey</code></h3></a>
|
|
<p align="justify">
|
|
Returns data of the user and course of a session,
|
|
given an identifier of session passed to the plugin from SWAD.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>sessionID</strong>: string passed as parameter to the plugin from SWAD.</li>
|
|
<li><strong>appKey</strong>: string, key used by the application.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>userCode</strong>: integer, unique identifier of the user.</li>
|
|
<li><strong>degreeCode</strong>: integer.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
<li><strong>wsKey</strong>: string, identifier used in the calls to other operations.</li>
|
|
<li><strong>userNickname</strong>: string, user's nickname (without @).</li>
|
|
<li><strong>userID</strong>: string, DNI/passport of the user.</li>
|
|
<li><strong>userSurname1</strong>: string.</li>
|
|
<li><strong>userSurname2</strong>: string.</li>
|
|
<li><strong>userFirstname</strong>: string.</li>
|
|
<li><strong>userPhoto</strong>: string
|
|
with the full URL of a JPG image
|
|
of size 150 (width) × 200 (height).
|
|
If it is an empty string, the user
|
|
has no photo or it can not be shown.
|
|
</li>
|
|
<li><strong>userBirthday</strong>: string, in YYYYMMDD format.</li>
|
|
<li><strong>userRole</strong>: integer, maximum role of the user,
|
|
with one of the following 4 values:
|
|
<ul>
|
|
<li><var>0</var>: unknown, an error has occurred.</li>
|
|
<li><var>1</var>: invited, not enrolled in any course.</li>
|
|
<li><var>2</var>: student in all his/her courses.</li>
|
|
<li><var>3</var>: teacher in at aleast one of his/her courses.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>degreeName</strong>: string.</li>
|
|
<li><strong>courseName</strong>: string.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="getNewPassword"><h3 class="WS_FUNCTION"><code>getNewPassword</code></h3></a>
|
|
<p align="justify">
|
|
Sends a new password by e-mail.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>userID</strong>: string (DNI/passport, @nickname or email of the user).</li>
|
|
<li><strong>appKey</strong>: string, key used by the application.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>success</strong>: integer. For compatibility with other functions,
|
|
this function returns a number > 0 (currently 1) on success,
|
|
and a number <= 0 (currently 0) on error.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="getCourses"><h3 class="WS_FUNCTION"><code>getCourses</code></h3></a>
|
|
<p align="justify">
|
|
Returns the list of courses to which the user belongs.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numCourses</strong>: integer, number of courses.</li>
|
|
<li><strong>coursesArray</strong>: list of elements,
|
|
where each element is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>courseCode</strong>: integer, unique identifier for each course.</li>
|
|
<li><strong>userRole</strong>: integer, role of the user in the course,
|
|
with one of the following 3 values:
|
|
<ul>
|
|
<li><var>0</var>: unknown, an error has occurred.</li>
|
|
<li><var>2</var>: student in this course.</li>
|
|
<li><var>3</var>: teacher in this course.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>courseShortName</strong>: string.</li>
|
|
<li><strong>courseFullName</strong>: string.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="getCourseInfo"><h3 class="WS_FUNCTION"><code>getCourseInfo</code></h3></a>
|
|
<p align="justify">
|
|
Returns information about the course.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
<li><strong>infoType</strong>: string,
|
|
with one of the following 7 values:
|
|
<ul>
|
|
<li><var>introduction</var>: introduction to the course.</li>
|
|
<li><var>guide</var>: teaching guide of the course.</li>
|
|
<li><var>lectures</var>: lectures syllabus.</li>
|
|
<li><var>practicals</var>: practicals (laboratory) syllabus.</li>
|
|
<li><var>bibliography</var>: bibliography.</li>
|
|
<li><var>FAQ</var>: FAQ.</li>
|
|
<li><var>links</var>: links.</li>
|
|
<li><var>assessment</var>: info on assessment system.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>infoSrc</strong>: string,
|
|
with one of the following 6 values:
|
|
<ul>
|
|
<li><var>none</var>: no info. <strong>infoTxt</strong> will be empty.</li>
|
|
<li><var>editor</var>: internal editor. <strong>infoTxt</strong> will contain a full XHTML page.</li>
|
|
<li><var>plainText</var>: plain text. <strong>infoTxt</strong> will contain a full XHTML page.</li>
|
|
<li><var>richText</var>: rich text. <strong>infoTxt</strong> will contain a full XHTML page.</li>
|
|
<li><var>page</var>: web page, in HTML format.
|
|
<strong>infoTxt</strong> will contain a full HTML page.
|
|
If the page contain images or other archives, the result will be incomplete,
|
|
because only the main page is returned.</li>
|
|
<li><var>URL</var>: URL address. <strong>infoTxt</strong> will contain the URL in plain text.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>infoTxt</strong>: string with the information.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="getGroupTypes"><h3 class="WS_FUNCTION"><code>getGroupTypes</code></h3></a>
|
|
<p align="justify">
|
|
Returns the list of types of group of a course.
|
|
Before consulting the list of types of group,
|
|
this function opens automatically
|
|
the groups of the course that should be open.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numGroupTypes</strong>: integer, number of types of group.</li>
|
|
<li><strong>groupTypesArray</strong>: list of elements,
|
|
where each element is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>groupTypeCode</strong>: integer, identifier of the type of group.</li>
|
|
<li><strong>groupTypeName</strong>: string
|
|
with the name of the type of group
|
|
(for example: "Theory", "Lab").</li>
|
|
<li><strong>mandatory</strong>: integer. If not 0 ⇒
|
|
the enrollment in group(s) of this type is mandatory
|
|
for students of the course,
|
|
if there is at least a group of that type open and with vacancies.</li>
|
|
<li><strong>multiple</strong>: integer. If not 0 ⇒
|
|
the students of the course can enroll
|
|
in more than a group of this type.</li>
|
|
<li><strong>openTime</strong>: integer of 32 bits with sign,
|
|
<a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.
|
|
If 0 ⇒ the teachers have not set a time to open automatically the groups of this type.
|
|
If not 0 and it corresponds to a future time ⇒
|
|
the groups of this type will be opened
|
|
automatically at that time.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="getGroups"><h3 class="WS_FUNCTION"><code>getGroups</code></h3></a>
|
|
<p align="justify">
|
|
Returns the list of all the groups of a course.
|
|
Before consulting the list of types of group,
|
|
this function opens automatically
|
|
the groups of the course that should be open.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numGroups</strong>: integer, number of groups.</li>
|
|
<li><strong>groupsArray</strong>: list of elements,
|
|
where each element is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>groupCode</strong>: integer, unique identifier for each group.</li>
|
|
<li><strong>groupName</strong>: string with the name of the group
|
|
(for example: "A", "B", "Morning", "Afternoon").</li>
|
|
<li><strong>groupTypeCode</strong>: integer, identifier of the type of group to which this group belongs.</li>
|
|
<li><strong>groupTypeName</strong>: string with the name of the type of group
|
|
(for example: "Theory", "Lab").</li>
|
|
<li><strong>open</strong>: integer. If not 0 ⇒ the group is open,
|
|
meaning that the students can enroll in or remove from the group.</li>
|
|
<li><strong>maxStudents</strong>: integer, maximum number of students in the group.
|
|
If < 0 ⇒ there is no limit of students in the group.</li>
|
|
<li><strong>numStudents</strong>: integer, current number of students in the group.</li>
|
|
<li><strong>fileZones</strong>: integer. If not 0 ⇒ the file zones for this group are enabled.</li>
|
|
<li><strong>member</strong>: integer. If not 0 ⇒ the logged user belongs to this group.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="sendMyGroups"><h3 class="WS_FUNCTION"><code>sendMyGroups</code></h3></a>
|
|
<p align="justify">
|
|
It sends to the server a list with all the groups in a course
|
|
to which the logged user wants to belong.
|
|
It tries to enroll the user in those groups if possible,
|
|
and remove from the groups not in the list.
|
|
If all the changes are not possible, no change is performed.
|
|
Returns the updated list of all the groups of the course
|
|
after the changes performed.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
<li><strong>myGroups</strong>: string.
|
|
List of codes of groups (each code is an integer number)
|
|
to which the user wants to belong, separated by commas.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>success</strong>: integer.
|
|
If 0 ⇒ it was impossible to satisfy all the requested changes,
|
|
no change performed.
|
|
If not 0 ⇒ all the requested changes
|
|
have been performed with success.
|
|
</li>
|
|
<li><strong>numGroups</strong>: integer, number of groups.</li>
|
|
<li><strong>groupsArray</strong>: list of elements,
|
|
with identical format to that of the list <strong>groupsArray</strong>
|
|
returned by the function <a href="#getGroups"><code>getGroups</code></a>.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="getDirectoryTree"><h3 class="WS_FUNCTION"><code>getDirectoryTree</code></h3></a>
|
|
<p align="justify">
|
|
Returns the full tree of a file zone (documents, shared files or marks) in a course or a group.
|
|
The logged user must belong to the course or the group.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
<li><strong>groupCode</strong>: integer,
|
|
if <= 0 ⇒ no group specified,
|
|
the zone corresponds to the whole course.</li>
|
|
<li><strong>treeCode</strong>: integer,
|
|
with one of the following 3 values:
|
|
<ul>
|
|
<li><var>1</var>: documents zone.
|
|
To download a file,
|
|
call <a href="#getFile"><code>getFile</code></a>.
|
|
</li>
|
|
<li><var>2</var>: shared files zone.
|
|
To download a file,
|
|
call <a href="#getFile"><code>getFile</code></a>.
|
|
</li>
|
|
<li><var>3</var>: marks zone.
|
|
To view marks,
|
|
call <a href="#getMarks"><code>getMarks</code></a>
|
|
or <a href="#getFile"><code>getFile</code></a>:
|
|
<ul>
|
|
<li>
|
|
if the logged user is a student in the course/group,
|
|
the client should call <a href="#getMarks"><code>getMarks</code></a>
|
|
to view the student's specific marks.
|
|
</li>
|
|
<li>
|
|
if the logged user is a teacher in the course/group,
|
|
the client should call <a href="#getFile"><code>getFile</code></a>
|
|
to download the HTML file with the marks of several students.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>tree</strong>: string with the full tree in XML format.<br />
|
|
Example:<br />
|
|
<pre>
|
|
<tree>
|
|
<dir name="Logos">
|
|
<file name="prado48x48.gif">
|
|
<code>103482</code>
|
|
<size>2026</size>
|
|
<time>1334483747</time>
|
|
<license>CC by-nc-sa</license>
|
|
<publisher>Antonio Cañas Vargas</publisher>
|
|
<photo>http://openswad.org/swad/photo/nQwJwD6jYd.jpg</photo>
|
|
</file>
|
|
<file name="swad48x48.gif">
|
|
<code>103491</code>
|
|
<size>1982</size>
|
|
<time>1334483747</time>
|
|
<license>CC by-nc-sa</license>
|
|
<publisher>Antonio Cañas Vargas</publisher>
|
|
<photo>http://openswad.org/swad/photo/nQwJwD6jYd.jpg</photo>
|
|
</file>
|
|
</dir>
|
|
<file name="Mejoras futuras.pdf">
|
|
<code>97910</code>
|
|
<size>224595</size>
|
|
<time>1334483747</time>
|
|
<license>CC by-nc-sa</license>
|
|
<publisher>Antonio Cañas Vargas</publisher>
|
|
<photo>http://openswad.org/swad/photo/nQwJwD6jYd.jpg</photo>
|
|
</file>
|
|
</tree>
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="getFile"><h3 class="WS_FUNCTION"><code>getFile</code></h3></a>
|
|
<p align="justify">
|
|
This function must be called each time the user wants to download a file
|
|
from a documents zone or a shared files zone in a course or a group.
|
|
The logged user must belong to the course or group.
|
|
The function counts the access as a visit to the file
|
|
and returns information about the file.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.
|
|
</li>
|
|
<li><strong>fileCode</strong>: integer,
|
|
corresponding to an element <code><code></code>
|
|
of the XML tree returned by <a href="#getDirectoryTree"><code>getDirectoryTree</code></a>.
|
|
If the file code corresponds to an HTML file of marks
|
|
(<code>treeCode</code> = 3 in <a href="#getDirectoryTree"><code>getDirectoryTree</code></a>,
|
|
the requester should be a student in the course/group.
|
|
If the logged user is a teacher, the client should call
|
|
<a href="#getMarks"><code>getMarks</code></a> instead <code>getFile</code>.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>fileName</strong>: string, name of the file.<br />
|
|
Example: <code>doc.pdf</code></li>
|
|
<li><strong>URL</strong>: string, full URL for downloading the file.<br />
|
|
Example: <code>http://openswad.org/swad/tmp/1ACaVfIj_GT768AqLBxHNKyl9iRW688ntqPW86I8FZU/doc.pdf</code></li>
|
|
<li><strong>size</strong>: integer, size in bytes.</li>
|
|
<li><strong>time</strong>: integer of 32 bits with sign, <a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.</li>
|
|
<li><strong>license</strong>: string, license.<br />
|
|
Example: "CC by-nc-sa"</li>
|
|
<li><strong>publisherName</strong>: string, first name and surnames of the user who uploaded the file.</li>
|
|
<li><strong>publisherPhoto</strong>: string with the full URL of a JPG image (of the user who uploaded the file)
|
|
with size 150 (width) × 200 (height).
|
|
If is a string empty, the user
|
|
has no photo or it can not be shown.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
<a name="getMarks"><h3 class="WS_FUNCTION"><code>getMarks</code></h3></a>
|
|
<p align="justify">
|
|
Returns information about the marks (qualifications, scores) of the logged user (requester)
|
|
from a given HTML file of marks.
|
|
This function is allowed only for students. The requester must be a student in the course/group.
|
|
If the logged user is a teacher, the client should call
|
|
<a href="#getFile"><code>getFile</code></a> instead of <code>getMarks</code>.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>fileCode</strong>: integer,
|
|
corresponding to an element <code><code></code>
|
|
of the XML tree returned
|
|
by <a href="#getDirectoryTree"><code>getDirectoryTree</code></a>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>content</strong>: string with a full HTML page containing the marks of the requester.
|
|
It's the same content returned in <code>content</code>
|
|
by <a href="#getNotifications"><code>getNotifications</code></a>.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="getTestConfig"><h3 class="WS_FUNCTION"><code>getTestConfig</code></h3></a>
|
|
<p align="justify">
|
|
Returns the configuration of the tests of a course.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>pluggable</strong>: integer. If 0 ⇒ the tests can not be downloaded from the client application
|
|
and if this calls the function <a href="#getTests"><code>getTests</code></a>
|
|
it will get an empty list of questions;
|
|
if not 0 ⇒ the tests of the course with all the tags visible can be downloaded from the client application
|
|
using the function <a href="#getTests"><code>getTests</code></a>.</li>
|
|
<li><strong>numQuestions</strong>: integer, number total of questions of test visible and available for download.
|
|
If the course does not allow to export tests (pluggable = 0) ⇒ numQuestions = 0.
|
|
If the course has no visible tests questions ⇒ numQuestions = 0.</li>
|
|
<li><strong>minQuestions</strong>: integer, minimum number of questions in an exam.</li>
|
|
<li><strong>defQuestions</strong>: integer, default number of questions in an exam.</li>
|
|
<li><strong>maxQuestions</strong>: integer, maximum number of questions in an exam.</li>
|
|
<li><strong>feedback</strong>: string with the type of feedback for the user,
|
|
with one of the following 5 values:
|
|
<ul>
|
|
<li><var>nothing</var>: no feedback.</li>
|
|
<li><var>totalResult</var>: minimum feedback: only total score.</li>
|
|
<li><var>eachResult</var>: medium feedback: score of each question.</li>
|
|
<li><var>eachGoodBad</var>: high feedback: correct answer in each question.</li>
|
|
<li><var>fullFeedback</var>: maximum feedback: text of feedback.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="getTests"><h3 class="WS_FUNCTION"><code>getTests</code></h3></a>
|
|
<p align="justify">
|
|
Returns the self-assessment tests of a course.
|
|
This function should not be callled if the download of tests is not allowed in this course
|
|
(if the function <a href="#getTestConfig"><code>getTestConfig</code></a> returns pluggable = 0).
|
|
If in this case you call <a href="#getTests"><code>getTests</code></a>, the four returned lists devueltas will be empty.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong> integer.</li>
|
|
<li><strong>beginTime</strong>: integer of 32 bits with sign, <a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.
|
|
All the tags not hidden are returned without taking into account beginTime,
|
|
but only the questions (and answers) with an edition/change time
|
|
later than or equal to beginTime will be returned.
|
|
With this parameter, each time the client application requests a test update,
|
|
you can send the time of the prior update
|
|
(or 0 if it is the first update), minimizing the volume of data to be transferred.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>tags</strong>: list of all the tags not hidden,
|
|
without having into account beginTime,
|
|
where each tag is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>tagCode</strong>: integer, unique identifier for each tag.</li>
|
|
<li><strong>tagText</strong>: string.</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><strong>questions</strong>: list of questions with an edition/change time later than or equal to beginTime,
|
|
where each question is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>questionCode</strong>: integer, unique identifier for the question.</li>
|
|
<li><strong>answerType</strong>: string,
|
|
with one of the following 6 values:
|
|
<ul>
|
|
<li><var>int</var>: integer number.</li>
|
|
<li><var>float</var>: floating point number.</li>
|
|
<li><var>TF</var>: true / false.</li>
|
|
<li><var>uniqueChoice</var>: choice of a unique answer between several options.</li>
|
|
<li><var>multipleChoice</var>: choice of several answers between several options.</li>
|
|
<li><var>text</var>: string.</li>
|
|
</ul>
|
|
<li><strong>shuffle</strong>: integer. If not 0 ⇒ the answers can be shuffled.</li>
|
|
<li><strong>stem</strong>: string with the stem of the question.</li>
|
|
<li><strong>feedback</strong>: string with the feedback of the question.</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><strong>answers</strong>: list of answers of the returned questions,
|
|
where each answer is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>questionCode</strong>: integer.</li>
|
|
<li><strong>answerIndex</strong>: integer, index or position (0, 1, 2,...) of the answer inside the question.</li>
|
|
<li><strong>correct</strong>: integer. If not 0 ⇒ the answer is correct.</li>
|
|
<li><strong>answerText</strong>: string with the text of the answer.</li>
|
|
<li><strong>answerFeedback</strong>: string with the feedback for this answer
|
|
(only when <strong>answerType</strong> is <var>uniqueChoice</var>, <var>multipleChoice</var> or <var>text</var>).
|
|
</ul>
|
|
</li>
|
|
|
|
<li><strong>questionTags</strong>: list of tags of the returned questions:
|
|
<ul>
|
|
<li><strong>questionCode</strong>: integer.</li>
|
|
<li><strong>tagCode</strong>: integer.</li>
|
|
<li><strong>tagIndex</strong>: integer, index or position (0, 1, 2,...) of the tag inside the question.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="getTrivialQuestion"><h3 class="WS_FUNCTION"><code>getTrivialQuestion</code></h3></a>
|
|
<p align="justify">
|
|
Returns a random test question, selected from the "uniqueChoice" questions
|
|
in the courses of a given list of degrees,
|
|
and with a score in the interval [<code>lowerScore</code>, <code>upperScore</code>].
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by loginByUserPasswordKey or loginBySessionKey.</li>
|
|
<li><strong>degrees</strong>: string. It can contain one or more degree codes, separated by commas.</li>
|
|
<li><strong>lowerScore</strong>: float. lower limit of the question score between -1.0 and 1.0</li>
|
|
<li><strong>upperScore</strong>: float. upper limit of the question score between -1.0 and 1.0</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>question</strong>: data structure with the following fields:
|
|
<ul>
|
|
<li><strong>questionCode</strong>: integer, unique identifier for the question, > 0.
|
|
If no question found ⇒ a questionCode value <= 0 will be returned.</li>
|
|
<li><strong>answerType</strong>: string,
|
|
currently only the following value is returned:
|
|
<ul>
|
|
<li><var>uniqueChoice</var>: choice of a unique answer between several options.</li>
|
|
</ul>
|
|
<li><strong>shuffle</strong>: integer. If not 0 ⇒ the answers can be shuffled.</li>
|
|
<li><strong>stem</strong>: string with the stem of the question.</li>
|
|
<li><strong>feedback</strong>: string with the feedback of the question.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>answers</strong>: list of answers of the returned question, where each answer is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>questionCode</strong>: integer.</li>
|
|
<li><strong>answerIndex</strong>: integer, index or position (0, 1, 2,...) of the answer inside the question.</li>
|
|
<li><strong>correct</strong>: integer. If not 0 ⇒ the answer is correct.</li>
|
|
<li><strong>answerText</strong>: string with the text of the answer.</li>
|
|
<li><strong>answerFeedback</strong>: string with the feedback for this answer.
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="getUsers" ><h3 class="WS_FUNCTION"><code>getUsers</code></h3></a>
|
|
<p align="justify">
|
|
Returns the list of users of a given type (students or teachers)
|
|
enrolled in a course and group (code of group <= 0 means the whole course).
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
<li><strong>groupCode</strong>: integer (<= 0 means the whole course).</li>
|
|
<li><strong>userRole</strong>: integer, role of the users to be listed
|
|
(2=students;
|
|
3=teachers)
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numUsers</strong>: integer, number of users.</li>
|
|
<li><strong>usersArray</strong>: list of elements,
|
|
where each element is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>userCode</strong>: integer, unique identifier for each user.</li>
|
|
<li><strong>userNickname</strong>: string, user's nickname (without @).</li>
|
|
<li><strong>userID</strong>: string, DNI/passport of the user.
|
|
If the requester is a teacher in the selected course, the ID is shown.
|
|
If the requester is a student in the selected course, the ID is hidden.
|
|
</li>
|
|
<li><strong>userSurname1</strong>: string.</li>
|
|
<li><strong>userSurname2</strong>: string.</li>
|
|
<li><strong>userFirstname</strong>: string.</li>
|
|
<li><strong>userPhoto</strong>: string
|
|
with the full URL of a JPG image
|
|
of size 150 (width) × 200 (height).
|
|
If it is an empty string, the user
|
|
has no photo or it can not be shown.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="getAttendanceEvents"><h3 class="WS_FUNCTION"><code>getAttendanceEvents</code></h3></a>
|
|
<p align="justify">
|
|
Returns the list of the attendance events in a course available for the logged user
|
|
(associated to the whole course or to the groups to which the logged user belongs).
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numEvents</strong>: integer, number of attendance events.</li>
|
|
<li><strong>eventsArray</strong>: list of elements,
|
|
where each element is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>attendanceEventCode</strong>: integer, unique identifier for each attendance event.</li>
|
|
<li><strong>hidden</strong>: integer. If not 0 ⇒ this attendance event is hidden for students.</li>
|
|
<li><strong>userSurname1</strong>: string.</li>
|
|
<li><strong>userSurname2</strong>: string.</li>
|
|
<li><strong>userFirstname</strong>: string.</li>
|
|
<li><strong>userPhoto</strong>: string
|
|
with the full URL of a JPG image
|
|
of size 150 (width) × 200 (height).
|
|
If it is a string empty, the user
|
|
has no photo or it can not be shown.</li>
|
|
<li><strong>startTime</strong>: integer of 32 bits with sign, <a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.</li>
|
|
<li><strong>endTime</strong>: integer of 32 bits with sign, <a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.</li>
|
|
<li><strong>commentsTeachersVisible</strong>: integer. If not 0 ⇒ the comments made by teachers are visible by the students.</li>
|
|
<li><strong>title</strong>: string.</li>
|
|
<li><strong>text</strong>: string.</li>
|
|
<li><strong>groups</strong>: string.
|
|
List of codes of groups (each code is an integer number)
|
|
to which this attendance event is applicable.
|
|
If this list of group codes is empty ⇒
|
|
this attendance event is applicable to the whole course.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="sendAttendanceEvent"><h3 class="WS_FUNCTION"><code>sendAttendanceEvent</code></h3></a>
|
|
<p align="justify">
|
|
Sends an attendance event.
|
|
The logged user must be a teacher in the course.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>attendanceEventCode</strong>: integer, unique identifier for each attendance event.
|
|
<ul>
|
|
<li>If <= 0 ⇒ this is a new attendance event.</li>
|
|
<li>If > 0 ⇒ this is an existing attendance event
|
|
returned by <a href="#getAttendanceEvents"><code>getAttendanceEvents</code></a>.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
<li><strong>hidden</strong>: integer. If not 0 ⇒ this attendance event is hidden for students.</li>
|
|
<li><strong>startTime</strong>: integer of 32 bits with sign, <a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.</li>
|
|
<li><strong>endTime</strong>: integer of 32 bits with sign, <a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.</li>
|
|
<li><strong>commentsTeachersVisible</strong>: integer. If not 0 ⇒ the comments made by teachers are visible by the students.</li>
|
|
<li><strong>title</strong>: string.</li>
|
|
<li><strong>text</strong>: string.</li>
|
|
<li><strong>groups</strong>: string.
|
|
List of codes of groups (each code is an integer number)
|
|
to which this attendance event is applicable.
|
|
If this list of group codes is empty ⇒
|
|
this attendance event is applicable to the whole course.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>attendanceEventCode</strong>: integer, unique identifier of the attendance event, > 0 on success.
|
|
On error, this code will be <= 0.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="getAttendanceUsers"><h3 class="WS_FUNCTION"><code>getAttendanceUsers</code></h3></a>
|
|
<p align="justify">
|
|
Returns the list of users (students) in an attendance event.
|
|
The logged user must be teacher in the selected course.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>attendanceEventCode</strong>: integer,
|
|
one of the codes returned
|
|
by <a href="#getAttendanceEvents"><code>getAttendanceEvents</code></a>
|
|
or <a href="#sendAttendanceEvent"><code>sendAttendanceEvent</code></a>.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numUsers</strong>: integer, number of users.</li>
|
|
<li><strong>usersArray</strong>: list of elements,
|
|
where each element is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>userCode</strong>: integer, unique identifier for each user.</li>
|
|
<li><strong>userNickname</strong>: string, user's nickname (without @).</li>
|
|
<li><strong>userID</strong>: string, DNI/passport of the user.</li>
|
|
<li><strong>userSurname1</strong>: string.</li>
|
|
<li><strong>userSurname2</strong>: string.</li>
|
|
<li><strong>userFirstname</strong>: string.</li>
|
|
<li><strong>userPhoto</strong>: string
|
|
with the full URL of a JPG image
|
|
of size 150 (width) × 200 (height).
|
|
If it is an empty string, the user
|
|
has no photo or it can not be shown.
|
|
</li>
|
|
<li><strong>present</strong>: integer. If not 0 ⇒ this user has attended the event.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="sendAttendanceUsers"><h3 class="WS_FUNCTION"><code>sendAttendanceUsers</code></h3></a>
|
|
<p align="justify">
|
|
Send the list of users (students)
|
|
who have attended to an attendance event.
|
|
All users in this list will be marked as present;
|
|
other users formerly marked as present will be marked as absent when <code>setOthersAsAbsent</code> = 1.
|
|
The logged user must be teacher in the selected course.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>attendanceEventCode</strong>: integer,
|
|
one of the codes returned
|
|
by <a href="#getAttendanceEvents"><code>getAttendanceEvents</code></a>
|
|
or <a href="#sendAttendanceEvent"><code>sendAttendanceEvent</code></a>.
|
|
</li>
|
|
<li><strong>users</strong>: string, list of numbers separated by commas.
|
|
Each number is the user's code
|
|
(previously returned by <a href="#getAttendanceUsers"><code>getAttendanceUsers</code></a>)
|
|
of a student who attended this event.
|
|
</li>
|
|
<li><strong>setOthersAsAbsent</strong>: integer:
|
|
<ul>
|
|
<li>
|
|
0 ⇒ users from list <code>users</code> will be added to list of presents
|
|
and other users formerly marked as present will not be affected
|
|
</li>
|
|
<li>
|
|
1 ⇒ users from list <code>users</code> will be marked as present
|
|
and other users formerly marked as present will be marked as absent
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>success</strong>: integer. 1 on success, 0 on error (for example, if the event does not exist).</li>
|
|
<li><strong>numUsers</strong>: integer, number of users found in list and marked as present in the event.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="getNotifications"><h3 class="WS_FUNCTION"><code>getNotifications</code></h3></a>
|
|
<p align="justify">
|
|
Returns the list of recent notifications for the logged user.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>beginTime</strong>: integer of 32 bits with sign, <a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.
|
|
Only the notifications with time later than or equal to this parameter will be shown.
|
|
With this parameter, each time the application client requests an update of the notifications,
|
|
you can send the time of the former update (or 0 if it is the first update),
|
|
minimizing the volume of data to be transferred.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numNotifications</strong>: integer, number of notifications.</li>
|
|
<li><strong>notificationsArray</strong>: list of elements,
|
|
where each element is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>notifCode</strong>: integer.
|
|
Unique identifier for a notification.
|
|
When a user opens this notification,
|
|
you should call <a href="#markNotificationsAsRead"><code>markNotificationsAsRead</code></a> with this value.</li>
|
|
<li><strong>eventType</strong>: string,
|
|
with one of the following 18 values:
|
|
<ol>
|
|
<li><var>documentFile</var>: document.</li>
|
|
<li><var>sharedFile</var>: shared file.</li>
|
|
<li><var>assignment</var>: assignment.</li>
|
|
<li><var>examAnnouncement</var>: exam announcement.</li>
|
|
<li><var>marksFile</var>: marks/grades file.</li>
|
|
<li><var>enrollmentStudent</var>: I have been enrolled in a course as a student.</li>
|
|
<li><var>enrollmentTeacher</var>: I have been enrolled in a course as a teacher.</li>
|
|
<li><var>enrollmentRequest</var>: enrollment request.</li>
|
|
<li><var>timelineComment</var>: comment to one of my social publishings (posts or comments).</li>
|
|
<li><var>timelineFav</var>: fav to one of my social publishings (posts or comments).</li>
|
|
<li><var>timelineShare</var>: sharing of one of my social posts.</li>
|
|
<li><var>timelineMention</var>: mention to me in a social publishing (post or comment).</li>
|
|
<li><var>follower</var>: a user has followed me.</li>
|
|
<li><var>forumPostCourse</var>: message in a forum of one of my courses.</li>
|
|
<li><var>forumReply</var>: reply to a message in a forum.</li>
|
|
<li><var>notice</var>: notice (yellow note).</li>
|
|
<li><var>message</var>: message to me from another user.</li>
|
|
<li><var>survey</var>: survey.</li>
|
|
</ol>
|
|
</li>
|
|
<li><strong>eventCode</strong>: integer.
|
|
A non-unique code associated to some notifications.
|
|
It corresponds to the code of the document, message, assignment, etc., depending on <code>eventType</code>.</li>
|
|
<li><strong>eventTime</strong>: integer of 32 bits with sign, <a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.</li>
|
|
<li><strong>userNickname</strong>: string, user's nickname (without @).</li>
|
|
<li><strong>userSurname1</strong>: string.</li>
|
|
<li><strong>userSurname2</strong>: string.</li>
|
|
<li><strong>userFirstname</strong>: string.</li>
|
|
<li><strong>userPhoto</strong>: string
|
|
with the full URL of a JPG image
|
|
of size 150 (width) × 200 (height).
|
|
If it is a string empty, the user
|
|
has no photo or it can not be shown.</li>
|
|
<li><strong>location</strong>: string.</li>
|
|
<li><strong>status</strong>: integer, with the following meaning for each bit:
|
|
<ul>
|
|
<li>Bit 0 = 1 ⇒ the user wants to receive by email notifications
|
|
of this event type.</li>
|
|
<li>Bit 1 = 1 ⇒ the email has been sent.</li>
|
|
<li>Bit 2 = 1 ⇒ the user has read the event
|
|
that caused the notification.</li>
|
|
<li>Bit 3 = 1 ⇒ the event
|
|
that caused the notification was removed (the notification should be displayed as hidden).</li>
|
|
</ul>
|
|
The following combinations are possible:
|
|
<ul>
|
|
<li>X000: No email will be sent, event not read.</li>
|
|
<li>X001: Email pending, event not read.</li>
|
|
<li>X010: (impossible).</li>
|
|
<li>X011: Email sent, event not read.</li>
|
|
<li>X100: No email will be sent, event read.</li>
|
|
<li>X101: Email cancelled because the event has been read before to send it.</li>
|
|
<li>X110: (impossible).</li>
|
|
<li>X111: Email sent, event read.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>summary</strong>: string with a brief description of the notification, for example the subject of a message.</li>
|
|
<li><strong>content</strong>: string with the full content of the notification, for example the text of a message.
|
|
If <code>eventType</code> is <var>marksFile</var>,
|
|
<code>content</code> will be HTML code
|
|
with information about the marks (qualifications, scores)
|
|
of the logged student from an HTML file of marks.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="markNotificationsAsRead"><h3 class="WS_FUNCTION"><code>markNotificationsAsRead</code></h3></a>
|
|
<p align="justify">
|
|
It marks several notifications as read.
|
|
You should call this function when one or more notifications have been open / read by the user.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>notifications</strong>: string.
|
|
List of unique notification codes
|
|
to be marked as read, separated by commas.
|
|
Each code is an integer, a unique identifier of the notification
|
|
returned as <code>notifCode</code>
|
|
(not <code>eventCode</code>/<code>notificationCode</code>)
|
|
by <a href="#getNotifications"><code>getNotifications</code></a>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numNotifications</strong>: integer, number of notifications found in list and marked as read.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<a name="sendNotice"><h3 class="WS_FUNCTION"><code>sendNotice</code></h3></a>
|
|
<p align="justify">
|
|
Sends a public notice (yellow note) to a course.
|
|
The logged user must be a teacher in the course.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>courseCode</strong>: integer.</li>
|
|
<li><strong>body</strong>: string, body of the message.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>noticeCode</strong>: integer, unique identifier of the notice, > 0 on success.
|
|
On error, this code will be <= 0.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<a name="sendMessage"><h3 class="WS_FUNCTION"><code>sendMessage</code></h3></a>
|
|
<p align="justify">
|
|
It sends a message to one or more users.
|
|
</p>
|
|
<ul>
|
|
<li>Call parameters:
|
|
<ul>
|
|
<li><strong>wsKey</strong>: string, identifier returned by
|
|
<a href="#loginByUserPasswordKey"><code>loginByUserPasswordKey</code></a> or
|
|
<a href="#loginBySessionKey"><code>loginBySessionKey</code></a>.</li>
|
|
<li><strong>messageCode</strong>: integer.
|
|
<ul>
|
|
<li>If <code>messageCode</code> is 0,
|
|
this message will be not considered a reply of another message,
|
|
and <code>to</code> should contain at least one recipient.</li>
|
|
<li>If <code>messageCode</code> is not 0,
|
|
this message will be considered a reply to a message received in notifications.
|
|
In that case it must contain the code returned
|
|
by <a href="#getNotifications"><code>getNotifications</code></a> in <code>eventCode</code>
|
|
(for safety, the server will check that this code of message corresponds really
|
|
to a message received previously by the user logged by <code>wsKey</code>).</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>to</strong>: string.
|
|
It can contain one or more IDs, @nicknames or emails of the recipients of the message, separated by commas.
|
|
<ul>
|
|
<li>If <code>messageCode</code> is 0, <code>to</code> must have at least an ID, @nickname or email.</li>
|
|
<li>If <code>messageCode</code> is distinct of 0, <code>to</code> can be empty.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>subject</strong>: string, subject of the message.</li>
|
|
<li><strong>body</strong>: string, body of the message.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numUsers</strong>: integer, number of recipients.</li>
|
|
<li><strong>usersArray</strong>: list of elements,
|
|
where each element is a data structure, corresponding to a recipient, with the following fields:
|
|
<ul>
|
|
<li><strong>userCode</strong>: integer, unique identifier of the recipient.</li>
|
|
<li><strong>userNickname</strong>: string, nickname of the recipient (without @).</li>
|
|
<li><strong>userID</strong>: string, DNI/passport of the user,
|
|
really this function returns a hidden <code>userID</code>,
|
|
so you should not use this field.</li>
|
|
<li><strong>userSurname1</strong>: string, first surname of the recipient.</li>
|
|
<li><strong>userSurname2</strong>: string, second surname of the recipient.</li>
|
|
<li><strong>userFirstname</strong>: string, name of the recipient.</li>
|
|
<li><strong>userPhoto</strong>: string
|
|
with the full URL of a JPG image
|
|
of size 150 (width) × 200 (height).
|
|
If it is a string empty, the user
|
|
does not have photo or it can not be shown.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
|
|
</html>
|