mirror of https://github.com/acanas/swad-core.git
1889 lines
83 KiB
HTML
1889 lines
83 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 API</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;
|
|
}
|
|
.obsolete
|
|
{
|
|
color:#660000;
|
|
}
|
|
</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 />social workspace at a distance</a>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center">
|
|
<h1>SWAD plugins, web service and API documentation</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="https://openswad.org/en?usr=@acanas" target="_blank">Antonio Cañas Vargas</a>, 1999-2021
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left">
|
|
|
|
<h2>Plugins</h2>
|
|
|
|
<p style="text-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 style="text-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 style="text-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 style="text-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 style="text-align:justify">
|
|
The exchange of information 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 style="text-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 style="text-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="https://openswad.org/api/swad.wsdl">https://openswad.org/api/swad.wsdl</a></li>
|
|
<li><a href="https://swad.ugr.es/api/swad.wsdl">https://swad.ugr.es/api/swad.wsdl</a></li>
|
|
</ul>
|
|
|
|
<p style="text-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>SWAD API (Application Programming Interface): functions provided by SWAD web service</h2>
|
|
|
|
<p style="text-align:justify">
|
|
The SWAD web service provides the following functions:
|
|
</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><a href="#getAvailableRoles"><code>getAvailableRoles</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><a href="#getGames"><code>getGames</code></a></li>
|
|
<li><a href="#getMatches"><code>getMatches</code></a></li>
|
|
<!-- <li><a href="#playMatch"><code>playMatch</code></a></li> -->
|
|
<li><a href="#getMatchStatus"><code>getMatchStatus</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#answerMatchQuestion"><code>answerMatchQuestion</code></a></li>
|
|
|
|
<li><a href="#getUsers"><code>getUsers</code></a></li>
|
|
<li style="margin-bottom:1em;"><a href="#findUsers"><code>findUsers</code></a></li>
|
|
|
|
<li><a href="#getAttendanceEvents"><code>getAttendanceEvents</code></a></li>
|
|
<li><a href="#sendAttendanceEvent"><code>sendAttendanceEvent</code></a></li>
|
|
<li><a href="#removeAttendanceEvent"><code>removeAttendanceEvent</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>
|
|
|
|
<li><a href="#getLocation"><code>getLocation</code></a></li>
|
|
<li><a href="#sendMyLocation"><code>sendMyLocation</code></a></li>
|
|
<li><a href="#getLastLocation"><code>getLastLocation</code></a></li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="createAccount">createAccount</a></code></h3>
|
|
<p style="text-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>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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="loginByUserPasswordKey">loginByUserPasswordKey</a></code></h3>
|
|
<p style="text-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>: guest, not enroled in any course.</li>
|
|
<li><var>2</var>: student in all his/her courses.</li>
|
|
<li><var>3</var>: teacher in at least one of his/her courses.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="loginBySessionKey">loginBySessionKey</a></code></h3>
|
|
<p style="text-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>: guest, not enroled in any course.</li>
|
|
<li><var>2</var>: student in all his/her courses.</li>
|
|
<li><var>3</var>: teacher in at least one of his/her courses.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>degreeName</strong>: string.</li>
|
|
<li><strong>courseName</strong>: string.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getAvailableRoles">getAvailableRoles</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Get available roles in 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>roles</strong>: integer, with bits set (bit <em>i</em> = 1) on available roles, or clear (bit <em>i</em> = 0) in unavailable roles:
|
|
<ul>
|
|
<li><var>bit 0</var>: Unknown: User not logged in</li>
|
|
<li><var>bit 1</var>: Guest: User not belonging to any course</li>
|
|
<li><var>bit 2</var>: User: Student or teacher outside of her/his courses</li>
|
|
|
|
<li><var>bit 3</var>: Student: Student in the selected course</li>
|
|
<li><var>bit 4</var>: Non-editing teacher: Teacher in the selected course without permission to edit</li>
|
|
<li><var>bit 5</var>: Teacher: Teacher in the selected course with permission to edit</li>
|
|
|
|
<li><var>bit 6</var>: Degree admin: Administrator of the degree to which the selected course belongs</li>
|
|
<li><var>bit 7</var>: Center admin: Administrator of the center to which the selected course belongs</li>
|
|
<li><var>bit 8</var>: Institution admin: Administrator of the institution to which the selected course belongs</li>
|
|
<li><var>bit 9</var>: System admin: System administrator (also known as superuser)</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getNewPassword">getNewPassword</a></code></h3>
|
|
<p style="text-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.
|
|
If 0 ⇒ error (for example, if the event does not exist).
|
|
If not 0 ⇒ success.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getCourses">getCourses</a></code></h3>
|
|
<p style="text-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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getCourseInfo">getCourseInfo</a></code></h3>
|
|
<p style="text-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 />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getGroupTypes">getGroupTypes</a></code></h3>
|
|
<p style="text-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 enrolment 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 enrol
|
|
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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getGroups">getGroups</a></code></h3>
|
|
<p style="text-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 enrol 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 requester belongs to this group.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="sendMyGroups">sendMyGroups</a></code></h3>
|
|
<p style="text-align:justify">
|
|
It sends to the server a list with all the groups in a course
|
|
to which the requester wants to belong.
|
|
It tries to enrol 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 ⇒ error (it was impossible to satisfy all the requested changes,
|
|
no change performed).
|
|
If not 0 ⇒ success (all the requested changes
|
|
have been performed).
|
|
</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 />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getDirectoryTree">getDirectoryTree</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns the full tree of a file zone (documents, shared files or marks) in a course or a group.
|
|
The requester 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 requester 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 requester 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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getFile">getFile</a></code></h3>
|
|
<p style="text-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 requester 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:
|
|
<ul>
|
|
<li>an element <code><code></code>
|
|
of the XML tree returned by
|
|
<a href="#getDirectoryTree"><code>getDirectoryTree</code></a>.
|
|
</li>
|
|
<li>the value of <code>eventCode</code>
|
|
returned by <a href="#getNotifications"><code>getNotifications</code></a>
|
|
if <code>eventType</code> is <var>documentFile</var> or <var>sharedFile</var>.
|
|
</li>
|
|
<li>the value of <code>eventCode</code>
|
|
returned by <a href="#getNotifications"><code>getNotifications</code></a>
|
|
if the requester is a teacher and
|
|
<code>eventType</code> is <var>marksFile</var>.
|
|
</li>
|
|
</ul>
|
|
</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>
|
|
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getMarks">getMarks</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns information about the marks (qualifications, scores) of the requester
|
|
from a given HTML file of marks.
|
|
This function is allowed <strong>only for students</strong>.
|
|
The requester must be a student in the course/group.
|
|
If the requester 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:
|
|
<ul>
|
|
<li>an element <code><code></code>
|
|
of the XML tree returned by
|
|
<a href="#getDirectoryTree"><code>getDirectoryTree</code></a>.
|
|
</li>
|
|
<li>the value of <code>eventCode</code>
|
|
returned by <a href="#getNotifications"><code>getNotifications</code></a>
|
|
if the requester is a student and
|
|
<code>eventType</code> is <var>marksFile</var>.
|
|
</li>
|
|
</ul>
|
|
</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 />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getTestConfig">getTestConfig</a></code></h3>
|
|
<p style="text-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 class="obsolete"><strong>feedback</strong> (obsolete, to be removed in 2021): 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>
|
|
<li><strong>visibility</strong>: integer, with the following meaning for each bit:
|
|
<ul>
|
|
<li>Bit 0 = 1 ⇒ the questions and answers texts are visible in test results.</li>
|
|
<li>Bit 1 = 1 ⇒ the feedback texts are visible in test results.</li>
|
|
<li>Bit 2 = 1 ⇒ which are the correct answers is visible in test results.</li>
|
|
<li>Bit 3 = 1 ⇒ the score of each question is visible in test results.</li>
|
|
<li>Bit 4 = 1 ⇒ the total score of an exam is visible in test results.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getTests">getTests</a></code></h3>
|
|
<p style="text-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>tagsArray</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>questionsArray</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>answersArray</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>questionTagsArray</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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getTrivialQuestion">getTrivialQuestion</a></code></h3>
|
|
<p style="text-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>answersArray</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%ellip;) 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 />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getGames">getGames</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns the list of visible (not hidden) games in a given 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>numGames</strong>: integer, number of games.</li>
|
|
<li><strong>gamesArray</strong>: list of elements,
|
|
where each element is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>gameCode</strong>: integer, unique identifier for each game.</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>title</strong>: string.</li>
|
|
<li><strong>text</strong>: string.</li>
|
|
<li><strong>numQuestions</strong>: integer, number of questions in game.</li>
|
|
<li><strong>maxGrade</strong>: float ≥ 0, maximum grade in game.</li>
|
|
<li><strong>visibility</strong>: integer, with the following meaning for each bit:
|
|
<ul>
|
|
<li>Bit 0 = 1 ⇒ the questions and answers texts are visible in match results.</li>
|
|
<li>Bit 1 = 1 ⇒ the feedback texts are visible in match results.</li>
|
|
<li>Bit 2 = 1 ⇒ which are the correct answers is visible in match results.</li>
|
|
<li>Bit 3 = 1 ⇒ the score of each question is visible in match results.</li>
|
|
<li>Bit 4 = 1 ⇒ the total score of the match is visible in match results.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getMatches">getMatches</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns the list of matches in a given game,
|
|
associated to the whole course or to the groups to which the requester 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>
|
|
<li><strong>gameCode</strong>: integer, identifier of the game.
|
|
The code must be a valid value > 0 corresponding to an existing game
|
|
returned by <a href="#getGames"><code>getGames</code></a>.
|
|
The requester must be a student in the course.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numMatches</strong>: integer, number of matches.</li>
|
|
<li><strong>matchesArray</strong>: list of elements,
|
|
where each element is a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>matchCode</strong>: integer, unique identifier for each match.</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>title</strong>: string.</li>
|
|
<li><strong>questionIndex</strong>: integer.</li>
|
|
<li><strong>groups</strong>: string.
|
|
List of codes of groups (each code is an integer number)
|
|
to which this match is applicable.
|
|
If this list of group codes is empty ⇒
|
|
this match is applicable to the whole course.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getMatchStatus">getMatchStatus</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Get match status to be refreshed in student's screen.
|
|
This function should be called:
|
|
<ul>
|
|
<li>from time to time (e.g. 3 seconds)</li>
|
|
<li>just after calling <a href="#answerMatchQuestion"><code>answerMatchQuestion</code></a></li>
|
|
</ul>
|
|
and the screen should be refreshed according to the status returned.
|
|
|
|
</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>gameCode</strong>: integer, identifier of the game.
|
|
The code must be a valid value > 0 corresponding to an existing game
|
|
returned by <a href="#getGames"><code>getGames</code></a>.
|
|
The requester must be a student in the course.
|
|
</li>
|
|
<li><strong>matchCode</strong>: integer, identifier of the match.
|
|
The code must be a valid value > 0 corresponding to an existing match
|
|
returned by <a href="#getMatches"><code>getMatches</code></a>.
|
|
The requester must be a student in the course, and belong to the groups,
|
|
to which this match is associated.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>matchCode</strong>: integer, unique identifier of the match.
|
|
<ul>
|
|
<li>If > 0, the teacher's screen is showing the answers and the student has permission to answer.
|
|
The caller may draw buttons for the options and call
|
|
<a href="#answerMatchQuestion"><code>answerMatchQuestion</code></a>
|
|
if the student either chooses an option or chooses to remove his/her answer.
|
|
</li>
|
|
<li>If = 0, the match is in a status where the student can not answer
|
|
(the match has not started, or has finished, or is in pause, or is showing results).</li>
|
|
<li>If < 0, an error has happened, the requester can not join the match.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>questionIndex</strong>: integer
|
|
<ul>
|
|
<li>0 ⇒ before first question, the match has not started</li>
|
|
<li>1, 2, 3… ⇒ index of current question</li>
|
|
<li>big number (currently 2<sup>31</sup> - 1 = 2147483647) ⇒ after last question, the match has finished</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>numAnswers</strong>: integer, number of options (a, b, c…) in question (only when questionIndex is 1, 2, 3…)</li>
|
|
<li><strong>answerIndex</strong>: integer
|
|
<ul>
|
|
<li>If < 0 ⇒ no answer selected.</li>
|
|
<li>If ≥ 0 ⇒ index (0, 1, 2…) of the answer selected (only when questionIndex is 1, 2, 3…).</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="answerMatchQuestion">answerMatchQuestion</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Send an answer to the current question in a match.
|
|
The requester should call this function only if <a href="#getMatchStatus"><code>getMatchStatus</code></a>
|
|
has returned matchCode > 0.
|
|
After calling this function, the requester should call
|
|
<a href="#getMatchStatus"><code>getMatchStatus</code></a>
|
|
again in order to get the current status of the match before refreshing the screen.
|
|
</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>gameCode</strong>: integer, identifier of the game.
|
|
The code must be a valid value > 0 corresponding to an existing game
|
|
returned by <a href="#getGames"><code>getGames</code></a>.
|
|
The requester must be a student in the course.
|
|
</li>
|
|
<li><strong>matchCode</strong>: integer, identifier of the match.</li>
|
|
<li><strong>questionIndex</strong>: integer, index of question (1, 2, 3…).</li>
|
|
<li><strong>answerIndex</strong>: integer.
|
|
<ul>
|
|
<li>If < 0 ⇒ no answer selected.</li>
|
|
<li>If ≥ 0 ⇒ index (0, 1, 2…) of the answer selected.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>matchCode</strong>: integer, unique identifier of the match.
|
|
<ul>
|
|
<li>> 0 on success.</li>
|
|
<li>≤ 0 on error.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getUsers">getUsers</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns the list of users with a given role (students or teachers)
|
|
enroled in a course (and optionally in some groups of 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>groups</strong>: string.
|
|
List of codes of groups (each code is an integer number, all the groups must belong to the course).<br />
|
|
If the list is empty, the whole course will be used. </li>
|
|
<li><strong>userRole</strong>: integer, role of the users to be listed,
|
|
with one of the following 2 values:
|
|
<ul>
|
|
<li><var>2</var>: students.</li>
|
|
<li><var>3</var>: teachers.</li>
|
|
</ul>
|
|
</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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="findUsers">findUsers</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns a list of users whose full name contains the words given in filter.
|
|
</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
|
|
(≤ 0 ⇒ users from the whole platform;
|
|
> 0 ⇒ users from the course given by <code>courseCode</code>).
|
|
</li>
|
|
<li><strong>filter</strong>: string, one or several words separated by spaces.<br />
|
|
Only those users whose full name will contain
|
|
all the words in <code>filter</code> as substrings will be returned,
|
|
provided that the two following conditions are satisfied:
|
|
<ul>
|
|
<li>The length of the longest word in <code>filter</code> must be ≥ a given <var>n</var>.
|
|
Eg. For <var>n</var> = 3, "Bruce Lee" is valid, "B Le" is not valid.
|
|
</li>
|
|
<li>The total number of characters in all the words
|
|
(not counting spaces) must be ≥ a given <var>m</var>.
|
|
Eg. For <var>m</var> = 7, "Bruce Lee" is valid, but "Bruce" or "Lee" are not valid.
|
|
</li>
|
|
</ul>
|
|
<var>n</var> and <var>m</var> can change in the server side.
|
|
A client should delegate to the server.
|
|
If any of these two conditions is not satisfied,
|
|
a negative value is returned in <code>numUsers</code>, indicating filter too short.
|
|
</li>
|
|
<li><strong>userRole</strong>: integer, role of the users to be listed,
|
|
with one of the following 4 values:
|
|
<ul>
|
|
<li><var>0</var>: unknown, any role (guests, students, teachers).</li>
|
|
<li><var>1</var>: guests, not enroled in any course.</li>
|
|
<li><var>2</var>: students.</li>
|
|
<li><var>3</var>: teachers.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>numUsers</strong>: integer, number of users found. If < 0 ⇒ filter is too short.</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 has permission to see the user's ID, the ID is shown.
|
|
If not, 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 />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getAttendanceEvents">getAttendanceEvents</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns the list of the attendance events in a course available for the requester
|
|
(associated to the whole course or to the groups to which the requester 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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="sendAttendanceEvent">sendAttendanceEvent</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Sends an attendance event.
|
|
</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.
|
|
The requester must be a teacher in this course.
|
|
If <code>attendanceEventCode</code> > 0 ⇒
|
|
<code>courseCode</code> must be the course associated to the attendance event.
|
|
</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.
|
|
<ul>
|
|
<li>> 0 on success.</li>
|
|
<li>≤ 0 on error.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="removeAttendanceEvent">removeAttendanceEvent</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Removes an existing attendance event.
|
|
</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, identifier of the attendance event to be removed.
|
|
The code must be a valid value > 0 corresponding to an existing attendance event
|
|
returned by <a href="#getAttendanceEvents"><code>getAttendanceEvents</code></a>.
|
|
The requester must be a teacher in the course to which this event is associated.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>attendanceEventCode</strong>: integer, unique identifier of the attendance event.
|
|
<ul>
|
|
<li>> 0 on success.</li>
|
|
<li>≤ 0 on error.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getAttendanceUsers">getAttendanceUsers</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns the list of users (students) in an attendance event.
|
|
</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>.
|
|
The requester must be a teacher in the course to which this event is associated.
|
|
</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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="sendAttendanceUsers">sendAttendanceUsers</a></code></h3>
|
|
<p style="text-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.
|
|
</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>.
|
|
The requester must be a teacher in the course to which this event is associated.
|
|
</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.
|
|
If 0 ⇒ error (for example, if the event does not exist).
|
|
If not 0 ⇒ success.
|
|
</li>
|
|
<li><strong>numUsers</strong>: integer, number of users found in list and marked as present in the event.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<hr />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getNotifications">getNotifications</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns the list of recent notifications for the requester.
|
|
</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 19 values:
|
|
<ol>
|
|
<li><var>documentFile</var>: document.
|
|
To download the file, clients can call
|
|
<a href="#getFile"><code>getFile</code></a>
|
|
with the value returned in <code>eventCode</code>
|
|
as parameter <code>fileCode</code>.
|
|
</li>
|
|
<li><var>teachersFile</var>: teachers' file.</li>
|
|
<li><var>sharedFile</var>: shared file.
|
|
To download the file, clients can call
|
|
<a href="#getFile"><code>getFile</code></a>
|
|
with the value returned in <code>eventCode</code>
|
|
as parameter <code>fileCode</code>.
|
|
</li>
|
|
<li><var>assignment</var>: assignment.</li>
|
|
<li><var>examAnnouncement</var>: exam announcement.</li>
|
|
<li><var>marksFile</var>: marks/grades file.
|
|
<ul>
|
|
<li>If the requester is a student, <code>content</code>
|
|
will contain a full HTML page containing the marks of the requester.
|
|
The client application can also call <a href="#getMarks"><code>getMarks</code></a>
|
|
with the value returned in <code>eventCode</code>
|
|
as parameter <code>fileCode</code>.
|
|
</li>
|
|
<li>If the requester is a teacher,
|
|
and he/she wants to download the file,
|
|
the client application can call <a href="#getFile"><code>getFile</code></a>
|
|
with the value returned in <code>eventCode</code>
|
|
as parameter <code>fileCode</code>.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><var>enrollmentStudent</var>: I have been enroled in a course as a student.</li>
|
|
<li><var>enrollmentTeacher</var>: I have been enroled in a course as a teacher.</li>
|
|
<li><var>enrollmentRequest</var>: enrolment 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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="markNotificationsAsRead">markNotificationsAsRead</a></code></h3>
|
|
<p style="text-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 />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="sendNotice">sendNotice</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Sends a public notice (yellow note) to a course.
|
|
The requester 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>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="sendMessage">sendMessage</a></code></h3>
|
|
<p style="text-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>
|
|
|
|
<hr />
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getLocation">getLocation</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns a location (institution, center, building and room)
|
|
for Wi-Fi-based positioning system given a MAC address.
|
|
</p>
|
|
<p style="text-align:justify">
|
|
In order to fill the database that stores the MAC-location pairs,
|
|
the client can call function <a href="#getAvailableRoles"><code>getAvailableRoles</code></a>
|
|
to check if the logged user is allowed to see the MAC address of the nearest Wi-Fi access point.
|
|
Only center, institution and system admins should be allowed to see it.
|
|
</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>MAC</strong>: string in <em>XXXXXXXXXXXX</em> format (12 hexadecimal digits)</li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>location</strong>: a data structure, corresponding to a location, with the following fields:
|
|
<ul>
|
|
<li><strong>institutionCode</strong>: integer, unique identifier of the institution.</li>
|
|
<li><strong>institutionShortName</strong>: string.</li>
|
|
<li><strong>institutionFullName</strong>: string.</li>
|
|
<li><strong>centerCode</strong>: integer, unique identifier of the center.</li>
|
|
<li><strong>centerShortName</strong>: string.</li>
|
|
<li><strong>centerFullName</strong>: string.</li>
|
|
<li><strong>buildingCode</strong>: integer, unique identifier of the building.</li>
|
|
<li><strong>buildingShortName</strong>: string.</li>
|
|
<li><strong>buildingFullName</strong>: string.</li>
|
|
<li><strong>floor</strong>: signed integer.</li>
|
|
<li><strong>roomCode</strong>: integer, unique identifier of the room
|
|
(≤ 0 ⇒ no room found for this MAC;
|
|
> 0 ⇒ room found).</li>
|
|
<li><strong>roomShortName</strong>: string.</li>
|
|
<li><strong>roomFullName</strong>: string.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="sendMyLocation">sendMyLocation</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Sends user's current location (room).
|
|
Periodically called from the client to send the user's current location to the server.
|
|
</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>roomCode</strong>: integer, unique identifier of the room
|
|
returned by <a href="#getLocation"><code>getLocation</code></a>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>success</strong>: integer.
|
|
If 0 ⇒ error (for example, if the room does not exist).
|
|
If not 0 ⇒ success.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 class="WS_FUNCTION"><code><a name="getLastLocation">getLastLocation</a></code></h3>
|
|
<p style="text-align:justify">
|
|
Returns the more recent location (institution, center, building and room) of a given user.
|
|
A user can only consult the location of another user
|
|
if the intersection of the centers of their courses is not empty.
|
|
Both users do not have to share any course,
|
|
but at least some course of each one has to share center.
|
|
</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>userCode</strong>: unique identifier of the user
|
|
returned, for example, by <a href="#findUsers"><code>findUsers</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li>Returns a data structure with the following fields:
|
|
<ul>
|
|
<li><strong>location</strong>: a data structure, corresponding to a location, with the following fields:
|
|
<ul>
|
|
<li><strong>institutionCode</strong>: integer, unique identifier of the institution.</li>
|
|
<li><strong>institutionShortName</strong>: string.</li>
|
|
<li><strong>institutionFullName</strong>: string.</li>
|
|
<li><strong>centerCode</strong>: integer, unique identifier of the center.</li>
|
|
<li><strong>centerShortName</strong>: string.</li>
|
|
<li><strong>centerFullName</strong>: string.</li>
|
|
<li><strong>buildingCode</strong>: integer, unique identifier of the building.</li>
|
|
<li><strong>buildingShortName</strong>: string.</li>
|
|
<li><strong>buildingFullName</strong>: string.</li>
|
|
<li><strong>floor</strong>: signed integer.</li>
|
|
<li><strong>roomCode</strong>: integer, unique identifier of the room
|
|
(≤ 0 ⇒ the user has no registered her/his last location, or you don't have permission to see it;
|
|
> 0 ⇒ room found).</li>
|
|
<li><strong>roomShortName</strong>: string.</li>
|
|
<li><strong>roomFullName</strong>: string.</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>checkinTime</strong>: integer of 32 bits with sign, <a href="http://en.wikipedia.org/wiki/Unix_time">Unix time</a>.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
|
|
</html>
|