1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml">
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <title>MySocials Project</title>
7 <link href="style.css" rel="stylesheet" type="text/css" />
11 <table width="779" border="0" align="center" cellpadding="0" cellspacing="0">
13 <td><table width="70%" border="0" cellspacing="0" cellpadding="0">
15 <td class="redbox"> </td>
18 <td height="45"><a href="index.html" class="logo">MySocials Project</a></td>
26 <td bgcolor="#E2E2D2" class="border" height="40"><table width="85%" border="0" cellspacing="0" cellpadding="0">
28 <td><a href="index.html" class="toplinks">MySocials API</a></td>
29 <td class="toplinks">|</td>
30 <td><a href="privacy.html" class="toplinks">Privacy</a></td>
31 <td class="toplinks">|</td>
32 <td><a href="development.html" class="toplinks">Development</a></td>
33 <td class="toplinks">|</td>
34 <td><a href="downloads.html" class="toplinks">Downloads</a></td>
42 <td bgcolor="#F3F3F3" class="border"><table width="100%" border="0"
43 cellspacing="0" cellpadding="0">
48 <td><table border="0" cellspacing="0" cellpadding="0">
50 <td class="heading"></td>
59 <h1>MySocials API</h1>
60 <h2>MySocials driver API</h2>
61 <p> MySocials driver is provided as a shared library (libmsa<service_name>.so). Structure <b>msa_module *d</b> includes information about the driver (name, identifier, pointers to driver functions). This structure is filled during initialization of the driver.
63 <h3>Driver interface</h3>
64 <p>Driver interface is described in file interface.h and consists of 4 functions:
66 <li><b>msa_module_init(struct msa_module* d)</b> — driver initialization;</li>
67 <li><b>msa_module_get_info(struct msa_module* d)</b> — getting information about driver;</li>
68 <li><b>msa_module->send(xmlDocPtr request, xmlDocPtr* response, const struct msa_module* info)</b> — request sending and response receiveing;</li>
69 <li><b>msa_module->shutdown(const struct msa_module*)</b> - driver shutdown.</li>
72 <h3>Driver initialization and shutting down</h3>
73 Driver initialization is performed by using <b>msa_module_init(struct msa_module* d)</b> function. Instance of structure which stores profile setting is created during initialization. Parameter d stores identifier of this instance.
75 Function <b>msa_module->shutdown(const struct msa_module*)</b> is used during program termination.
77 <h3>Interaction with driver</h3>
79 Fuction <b>msa_module->send(xmlDocPtr request, xmlDocPtr* response, const struct msa_module* info)</b> is used to perform requests to the driver.
80 Parameter <i>request</i> is a request in XML format. Description of structure of sending and receiveing data is described <a>here</a>.
81 Parameter <i>response</i> contains driver response in XML format.
82 Function <b>msa_module_get_info(struct msa_module* d)</b> is used to get information about driver (driver name and icon).
85 <h2>MySocials driver data structures</h2>
87 <p>Here you can see description of data structures which are used by MySocials driver. These structures are declared in <b>mysocials_driver.h</b> file which is available for other applications from mysocials-dev package.
91 <pre>enum error_type {
92 FAILURE, // Function finished with error
93 SUCCESS, // Function finished without error
94 ERROR_ALLOCATION_OF_MEMORY, // Allocation of memory
95 ERROR_NO_FUNCTION, // Defining function error
96 ERROR_INITIALIZATION_ALREADY_PASSED, // Re-initialization error
97 ERROR_IS_BUSY, // Module is busy
98 ERROR_SEND_DATA, // Data sending error
99 ERROR_PARSE_DATA // Data parsing error
103 <h3>Driver interface</h3>
104 <p>MySocials driver interface described in <b>msa_module</b> structure. Some of the fields of this stucture are filled before initialization by application (marked with **), the rest of it is filled during initialization.</p>
107 gchar *id; // Identifier
108 gchar *name; // External driver name
109 gchar* driverName; // Driver name for system purposes (equals driver identifier)
110 gchar *pic; // Icon coded in base64
111 gchar *proxy; // **Proxy server address or NULL
112 gint port; // **Proxy server port
114 /* Pointer to function for processing requests.
116 xmlRequest — request in XML format
117 xmlResponse — response in XML format
118 info — structure with driver settings
120 Function returns SUCCESS in case without errors, otherwise FAILURE.
123 error_type (*send)(char* xmlRequest, char** xmlResponse, struct msa_module *info)
125 /* Pointer to function for driver shutting down.
127 info — structure with driver settings
129 Function returns SUCCESS in case without errors, otherwise FAILURE.
132 error_type (*shutdown)(struct msa_module* info);
137 <h2>Format of XML requests and responses</h2>
138 <h3>Common format of driver request and response</h3>
139 <h4>Request format</h4>
141 <Request class="" function="" noAuthorize="true">
149 <li><i>noAuthorize</i> - flag which forbids driver to call WebAuth (optional, set to false by default) </li>
150 <li><i>class</i> - class which includes called function</li>
151 <li><i>function</i> - name of the function</li>
152 <li><i>Params</i> - set of parameters, stricly defined for each function</li>
155 <h4>Response format</h4>
157 <Response class="" function="" authorized="true" upload="..." download="...">
165 <li><i>authorized</i> - flag which indicates authorization during request performing (flag isn't set if error occures during request performing) </li>
166 <li><i>upload</i> - number of bytes sent to server</li>
167 <li><i>download</i> - number of bytes received from server</li>
170 <p>Following classes are supported:
172 <li><i>settings:</i> class for working with settings</li>
173 <li><i>profile:</i> class for receiving data about user's profile</li>
174 <li><i>friends:</i> class for receiving data about user's friends</li>
175 <li><i>messages:</i> class for receiving data about messages</li>
176 <li><i>photos:</i> class for working with photos</li>
177 <li><i>audio:</i> class for working with audio files</li>
178 <li><i>video:</i> class for working with video files</li>
179 <li><i>news:</i> class for working with news</li>
187 <Request class="settings" function="getSettings">
194 <Response class="settings" function="getSettings">
196 <string name="mid"> ... </string>
197 <string name="sid"> ... </string>
198 <string name="secret"> ... </string>
202 <p>Content of <i>Params</i> tag depends on the driver. It is recommended to save content of <i>Params</i> tag and send it to setup function without any changes.</p>
207 <Request class="settings" function="setSettings">
209 <string name="mid"> ... </string>
210 <string name="sid"> ... </string>
211 <string name="secret"> ... </string>
215 <p><i>Params</i> tag must contain data received from driver during <i>getSettings</i> request.</p>
216 <b>Response:</b> info message or error message.
218 <h4>getListMethods</h4>
221 <Request class="settings" function="getListMethods">
227 <Response class="settings" function="getListMethods">
229 <string function="..." class="..."> ... </string>
230 <string function="..." class="..."> ... </string>
236 <h4>testConnection</h4>
239 <Request class="settings" function="testConnection">
243 <b>Response:</b> info message or error message.
251 <Request class="profile" function="getProfile">
252 <Params id="...">
255 <p>Attribute <i>id</i> is an id of user whose profile is needed to be received (optional, equals id of owner of current account by default).</p>
258 <Response class="profile" function="getProfile">
259 <Params id="...">
260 <string name="FirstName"> ... </string>
261 <string name="NickName"> ... </string>
262 <string name="LastName"> ... </string>
263 <string name="Gender"> ... </string>
264 <string name="Birthday"> ... </string>
265 <string name="MobilePhone"> ... </string>
266 <string name="HomePhone"> ... </string>
267 <img name="Img"> ... </img>
268 <string name="CityName"> ... </string>
269 <string name="CountryName"> ... </string>
274 <h4>getBaseProfile</h4>
277 <Request class="profile" function="getBaseProfile">
278 <Params id="...">
281 <p>Attribute <i>id</i> is an id of user whose profile is needed to be received (optional, equals id of owner of current account by default).</p>
284 <Response class="profile" function="getBaseProfile">
285 <Params id="...">
286 <string name="FirstName"> ... </string>
287 <string name="NickName"> ... </string>
288 <string name="LastName"> ... </string>
296 <h4>getListFriends</h4>
299 <Request class="friends" function="getListFriends">
300 <Params id="...">
301 <number name="page"> ... </number>
302 <number name="pageSize"> ... </number>
307 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
308 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
309 <li><i>id</i> - user id (optional, equals id of owner of current account by default) </li>
313 <Response class="friends" function="getListFriends">
314 <Params id="...">
315 <array name="contactList" page="..." pageSize="..." quantity="...">
316 <struct name="contact" id="...">
317 <string name="FirstName"> ... </string>
318 <string name="NickName"> ... </string>
319 <string name="LastName"> ... </string>
320 <string name="FriendStatus"> ... </string>
321 <img name="Img"> ... </img>
328 <h4>deleteFriend</h4>
331 <Request class="friends" function ="deleteFriend">
332 <Params id="..."/>
335 <b>Response:</b> info message or error message.
343 <Request class="photos" function="createAlbum">
344 <Params id="...">
345 <string name="name"> ... </string>
346 <string name="description"> ... </string>
347 <string name="privacy">PRIVACY</string>
351 PRIVACY can have following values:
353 <li>SELF - created album will be available only for its owner; </li>
354 <li>ALL_FRIENDS - created album will be available for owner's friends;</li>
355 <li>FRIENDS_OF_FRIENDS - created album will be available only for owner's friends and their friends; </li>
356 <li>EVERYONE - created album will be available only for every user.</li>
358 <p>This set of values can be extended. If PRIVACY isn't set, driver use default setting for all new albums which are set by user.</p>
360 <li><i>id</i> - optional, equals id of owner of current account by default </li>
361 <li><i>name</i> - optional, equals "no_name" by default</li>
362 <li><i>description</i> - optional </li>
366 <Response class="photos" function="createAlbum">
367 <Params id="...">
368 <string name="albumId"> ... </string>
373 <h4>getListAlbums</h4>
376 <Request class="photos" function="getListAlbums">
377 <Params id="..."/>
380 <p><i>id</i> - optional, equals id of owner of current account by default.</p>
383 <Response class="photos" function="getListAlbums">
385 <array name="albumList" quantity="..." ownerId="...">
386 <struct name="album" id="...">
387 <string name="title"> ... </string>
388 <string name="description"> ... </string>
389 <string name="thumbId"> ... </string>
390 <img name="Img"> ... </img>
391 <number name="created"> ... </number>
392 <number name="updated"> ... </number>
393 <number name="size"> ... </number>
394 <number name="canUpload"> ... </number>
400 <p><i>canUpload</i> - optional, if this parameter isn't set, it means that album is available for current user.</p>
405 <Request class="photos" function = "uploadPhoto">
407 <string name="albumId"> ... </string>
408 <string name="albumName"> ... </string>
409 <string name="albumPrivacy"> ... </string>
410 <string name="albumDescription"> ... </string>
411 <string name="file"> ... </string>
412 <string name="fileName"> ... </string>
413 <string name="description"> ... </string>
414 <string name="tags"> ... </string>
419 <li>There have to be only one of parameters <i>albumName</i> or <i>albumId</i> in request.</li>
420 <li>If <i>albumId</i> is set, photo is uploaded to this album.</li>
421 <li>If <i>albumId</i> isn't specified, new album is created (with name <i>albumName</i>, description <i>albumDescription</i> and private settings <i>albumPrivacy</i>). </li>
422 <li>If both parameters <i>albumName</i> and <i>albumId</i> aren't specified, driver returns error message or photo is uploaded to common album, which is available in some services.</li>
423 <li>Parameter <i>tags</i> can not be supported by some services.</li>
424 <li>Parameter <i>file</i> contains full path to file for sending.</li>
425 <li>Parameter <i>fileName</i> contains name of file for upload.</li>
429 <Response class="photos" function = "uploadPhoto">
431 <string name="albumId"> ... </string>
432 <string name="photoId"> ... </string>
437 <h4>getListPhotos</h4>
440 <Request class="photos" function = "getListPhotos">
441 <Params id="...">
442 <string name="albumId"> ... </string>
443 <number name="page"> ... </number>
444 <number name="pageSize"> ... </number>
449 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
450 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
451 <li><i>id</i> - user id (optional, equals id of owner of current account by default) </li>
455 <Response class="photos" function="getListPhotos">
457 <array name="photosList" page="..." pageSize="..." quantity="..." ownerId="..." albumId="...">
458 <struct name="photo" id="..."/>
459 <string name="urlSmall"> ... </string>
460 <string name="urlBig"> ... </string>
461 <string name="urlOrig"> ... </string>
462 <string name="description"> ... </string>
463 <number name="created"> ... </number>
470 <h4>getListUserPhotos</h4>
473 <Request class="photos" function = "getListUserPhotos">
474 <Params id="...">
475 <number name="page"> ... </number>
476 <number name="pageSize"> ... </number>
481 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
482 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
483 <li><i>id</i> - user id (optional, equals id of owner of current account by default) </li>
487 <Response class="photos" function="getListUserPhotos">
489 <array name="photosList" page="..." pageSize="..." quantity="...">
490 <struct name="photo" id="..."/>
491 <string name="ownerId"> ... </string>
492 <string name="albumId"> ... </string>
493 <string name="urlSmall"> ... </string>
494 <string name="urlBig"> ... </string>
495 <string name="urlOrig"> ... </string>
496 <string name="description"> ... </string>
497 <number name="created"> ... </number>
504 <h4>getListPhotoTags</h4>
507 <Request class="photos" function = "getListPhotoTags">
509 <string name="ownerId"> ... </string>
510 <string name="albumId"> ... </string>
511 <string name="photoId"> ... </string>
517 <Response class="photos" function="getListPhotoTags">
519 <array name="tagsList" quantity="..." ownerId="..." albumId="..." photoId="...">
520 <struct name="tag" id="..."/>
521 <string name="userId"> ... </string>
522 <string name="text"> ... </string>
523 <number name="created"> ... </number>
529 <p>Parameter <i>userId</i> is an id of user which is marked on photo (optional).</p>
531 <h4>getListFavoritePhotos</h4>
534 <Request class="photos" function = "getListFavoritePhotos">
535 <Params id="...">
536 <number name="page"> ... </number>
537 <number name="pageSize"> ... </number>
542 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
543 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
544 <li><i>id</i> - user id (optional, equals id of owner of current account by default) </li>
548 <Response class="photos" function="getListFavoritePhotos">
550 <array name="photosList" page="..." pageSize="..." quantity="...">
551 <struct name="photo" id="..."/>
552 <string name="ownerId"> ... </string>
553 <string name="albumId"> ... </string>
554 <string name="urlSmall"> ... </string>
555 <string name="urlBig"> ... </string>
556 <string name="urlOrig"> ... </string>
557 <string name="description"> ... </string>
558 <number name="created"> ... </number>
568 <Request class="photos" function = "getPhoto">
570 <string name="url"> ... </string>
571 <string name="path"> ... </string>
575 <b>Response:</b> info message or error message.
577 <h4>getListPhotoComments</h4>
580 <Request class="photos" function = "getListPhotoComments">
582 <string name="ownerId"> ... </string>
583 <string name="albumId"> ... </string>
584 <string name="photoId"> ... </string>
585 <number name="page"> ... </number>
586 <number name="pageSize"> ... </number>
591 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
592 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
596 <Response class="photos" function="getListPhotoComments">
598 <array name="commentsList" page="..." pageSize="..." quantity="..." ownerId="..." albumId="..." photoId="...">
599 <struct name="comment" id="..."/>
600 <string name="ParentId"> ... </string>
601 <string name="SenderId"> ... </string>
602 <string name="SenderName"> ... </string>
603 <string name="Time"> ... </string>
604 <string name="Text"> ... </string>
610 <p>Parameter <i>ParentId</i> is an id of previous comment, if there is such one (optional).</p>
612 <h4>sendPhotoComment</h4>
615 <Request class="photos" function="sendPhotoComment">
617 <string name="ownerId"> ... </string>
618 <string name="albumId"> ... </string>
619 <string name="photoId"> ... </string>
620 <string name="text"> ... </string>
624 <b>Response:</b> info message or error message.
629 <h4>getListOutboxMessages</h4>
632 <Request class="messages" function="getListOutboxMessages">
634 <number name="page"> ... </number>
635 <number name="pageSize"> ... </number>
636 <number name="timeOffset"> ... </number>
641 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
642 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
643 <li><i>timeOffset</i> - time offset for requested messages</li>
647 <Response class="messages" function = "getListOutboxMessages">
649 <array name="messageList" page="..." pageSize="..." quantity="...">
650 <struct name="message" id="...">
651 <string name="SenderId"> ... </string>
652 <string name="SenderName"> ... </string>
653 <array name="recipientList" quantity="...">
654 <struct name="recipient">
655 <string name="RecipientId"> ... </string>
656 <string name="RecipientName"> ... </string>
659 <string name="Time"> ... </string>
660 <string name="Title"> ... </string>
661 <string name="Text"> ... </string>
662 <string name="Status"> ... </string>
663 <attachment id="..." ownerId="..." type="...">
671 <p>Parameter <i>attachment</i> is optional, its content depends on attribute <i>type</i> and can have following values:</p>
673 <attachment id="..." ownerId="..." type="image">
674 <string name="name"> ... </string>
675 <string name="albumId"> ... </string>
676 <string name="urlSmall"> ... </string>
677 <string name="urlBig"> ... </string>
680 <attachment id="..." ownerId="..." type="video">
681 <string name="name"> ... </string>
682 <string name="url"> ... </string>
683 <number name="duration"> ... </number>
684 <string name="urlImage"> ... </string>
687 <attachment id="..." ownerId="..." type="audio">
688 <string name="name"> ... </string>
689 <string name="url"> ... </string>
690 <number name="duration"> ... </number>
693 <attachment id="..." ownerId="..." type="link">
694 <string name="name"> ... </string>
695 <string name="url"> ... </string>
696 <string name="urlImage"> ... </string>
699 <attachment id="..." ownerId="..." type="note">
700 <string name="name"> ... </string>
701 <string name="url"> ... </string>
710 <h4>getListAudio</h4>
713 <Request class="audio" function="getListAudio">
714 <Params id="...">
720 <Response class="audio" function="getListAudio">
721 <Params id="...">
722 <array name="audioList" quantity="..." ownerId="...">
723 <struct name="audio" id="...">
724 <string name="title"> ... </string>
725 <string name="artist"> ... </string>
726 <number name="duration"> ... </number>
727 <string name="audio"> ...url... </string>
737 <h4>getListVideo</h4>
740 <Request class="video" function="getListVideo">
741 <Params id="...">
747 <Response class="video" function="getListVideo">
749 <array name="videoList" quantity="..." ownerId="...">
750 <struct name="video" id="...">
751 <string name="title"> ... </string>
752 <string name="description"> ... </string>
753 <number name="duration"> ... </number>
754 <img name="Img"> ...url... </img>
755 <string name="link"> ...url... </string>
756 <string name="url"> ...url to player... </string>
767 <h3>Info and error messages</h3>
768 <h4>Error message format</h4>
770 <Response class="systemMessages" function = "errorMessage">
772 <string name="moduleName"> ... </string>
773 <string name="code"> ... </string>
774 <string name="text"> ... </string>
775 <string name="comment"> ... </string>
776 <string name="type">user/internal/service </string>
781 <h4>Info message format</h4>
783 <Response class="systemMessages" function = "infoMessage">
785 <string name="moduleName"> ... </string>
796 <td><table width="92%" border="0" align="right" cellpadding="0"
799 <td class="copybox"> MySocials Project © 2011</td>
804 <td height="10"> </td>