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">About</a></td>
29 <td class="toplinks">|</td>
30 <td><a href="api.html" class="toplinks">MySocials API</a></td>
31 <td class="toplinks">|</td>
32 <td><a href="privacy.html" class="toplinks">Privacy</a></td>
33 <td class="toplinks">|</td>
34 <td><a href="development.html" class="toplinks">Development</a></td>
35 <td class="toplinks">|</td>
36 <td><a href="downloads.html" class="toplinks">Downloads</a></td>
44 <td bgcolor="#F3F3F3" class="border"><table width="100%" border="0"
45 cellspacing="0" cellpadding="0">
50 <td><table border="0" cellspacing="0" cellpadding="0">
52 <td class="heading"></td>
61 <h1>MySocials API</h1>
62 <h2>MySocials driver API</h2>
63 <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.
65 <h3>Driver interface</h3>
66 <p>Driver interface is described in file interface.h and consists of 4 functions:
68 <li><b>msa_module_init(struct msa_module* d)</b> — driver initialization;</li>
69 <li><b>msa_module_get_info(struct msa_module* d)</b> — getting information about driver;</li>
70 <li><b>msa_module->send(xmlDocPtr request, xmlDocPtr* response, const struct msa_module* info)</b> — request sending and response receiveing;</li>
71 <li><b>msa_module->shutdown(const struct msa_module*)</b> - driver shutdown.</li>
74 <h3>Driver initialization and shutting down</h3>
75 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.
77 Function <b>msa_module->shutdown(const struct msa_module*)</b> is used during program termination.
79 <h3>Interaction with driver</h3>
81 Fuction <b>msa_module->send(xmlDocPtr request, xmlDocPtr* response, const struct msa_module* info)</b> is used to perform requests to the driver.
82 Parameter <i>request</i> is a request in XML format. Description of structure of sending and receiveing data is described <a>here</a>.
83 Parameter <i>response</i> contains driver response in XML format.
84 Function <b>msa_module_get_info(struct msa_module* d)</b> is used to get information about driver (driver name and icon).
87 <h2>MySocials driver data structures</h2>
89 <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.
93 <pre>enum error_type {
94 FAILURE, // Function finished with error
95 SUCCESS, // Function finished without error
96 ERROR_ALLOCATION_OF_MEMORY, // Allocation of memory
97 ERROR_NO_FUNCTION, // Defining function error
98 ERROR_INITIALIZATION_ALREADY_PASSED, // Re-initialization error
99 ERROR_IS_BUSY, // Module is busy
100 ERROR_SEND_DATA, // Data sending error
101 ERROR_PARSE_DATA // Data parsing error
105 <h3>Driver interface</h3>
106 <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>
109 gchar *id; // Identifier
110 gchar *name; // External driver name
111 gchar* driverName; // Driver name for system purposes (equals driver identifier)
112 gchar *pic; // Icon coded in base64
113 gchar *proxy; // **Proxy server address or NULL
114 gint port; // **Proxy server port
116 /* Pointer to function for processing requests.
118 xmlRequest — request in XML format
119 xmlResponse — response in XML format
120 info — structure with driver settings
122 Function returns SUCCESS in case without errors, otherwise FAILURE.
125 error_type (*send)(char* xmlRequest, char** xmlResponse, struct msa_module *info)
127 /* Pointer to function for driver shutting down.
129 info — structure with driver settings
131 Function returns SUCCESS in case without errors, otherwise FAILURE.
134 error_type (*shutdown)(struct msa_module* info);
139 <h2>Format of XML requests and responses</h2>
140 <h3>Common format of driver request and response</h3>
141 <h4>Request format</h4>
143 <Request class="" function="" noAuthorize="true">
151 <li><i>noAuthorize</i> - flag which forbids driver to call WebAuth (optional, set to false by default) </li>
152 <li><i>class</i> - class which includes called function</li>
153 <li><i>function</i> - name of the function</li>
154 <li><i>Params</i> - set of parameters, stricly defined for each function</li>
157 <h4>Response format</h4>
159 <Response class="" function="" authorized="true" upload="..." download="...">
167 <li><i>authorized</i> - flag which indicates authorization during request performing (flag isn't set if error occures during request performing) </li>
168 <li><i>upload</i> - number of bytes sent to server</li>
169 <li><i>download</i> - number of bytes received from server</li>
172 <p>Following classes are supported:
174 <li><i>settings:</i> class for working with settings</li>
175 <li><i>profile:</i> class for receiving data about user's profile</li>
176 <li><i>friends:</i> class for receiving data about user's friends</li>
177 <li><i>messages:</i> class for receiving data about messages</li>
178 <li><i>photos:</i> class for working with photos</li>
179 <li><i>audio:</i> class for working with audio files</li>
180 <li><i>video:</i> class for working with video files</li>
181 <li><i>news:</i> class for working with news</li>
189 <Request class="settings" function="getSettings">
196 <Response class="settings" function="getSettings">
198 <string name="mid"> ... </string>
199 <string name="sid"> ... </string>
200 <string name="secret"> ... </string>
204 <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>
209 <Request class="settings" function="setSettings">
211 <string name="mid"> ... </string>
212 <string name="sid"> ... </string>
213 <string name="secret"> ... </string>
217 <p><i>Params</i> tag must contain data received from driver during <i>getSettings</i> request.</p>
218 <b>Response:</b> info message or error message.
220 <h4>getListMethods</h4>
223 <Request class="settings" function="getListMethods">
229 <Response class="settings" function="getListMethods">
231 <string function="..." class="..."> ... </string>
232 <string function="..." class="..."> ... </string>
238 <h4>testConnection</h4>
241 <Request class="settings" function="testConnection">
245 <b>Response:</b> info message or error message.
253 <Request class="profile" function="getProfile">
254 <Params id="...">
257 <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>
260 <Response class="profile" function="getProfile">
261 <Params id="...">
262 <string name="FirstName"> ... </string>
263 <string name="NickName"> ... </string>
264 <string name="LastName"> ... </string>
265 <string name="Gender"> ... </string>
266 <string name="Birthday"> ... </string>
267 <string name="MobilePhone"> ... </string>
268 <string name="HomePhone"> ... </string>
269 <img name="Img"> ... </img>
270 <string name="CityName"> ... </string>
271 <string name="CountryName"> ... </string>
276 <h4>getBaseProfile</h4>
279 <Request class="profile" function="getBaseProfile">
280 <Params id="...">
283 <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>
286 <Response class="profile" function="getBaseProfile">
287 <Params id="...">
288 <string name="FirstName"> ... </string>
289 <string name="NickName"> ... </string>
290 <string name="LastName"> ... </string>
298 <h4>getListFriends</h4>
301 <Request class="friends" function="getListFriends">
302 <Params id="...">
303 <number name="page"> ... </number>
304 <number name="pageSize"> ... </number>
309 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
310 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
311 <li><i>id</i> - user id (optional, equals id of owner of current account by default) </li>
315 <Response class="friends" function="getListFriends">
316 <Params id="...">
317 <array name="contactList" page="..." pageSize="..." quantity="...">
318 <struct name="contact" id="...">
319 <string name="FirstName"> ... </string>
320 <string name="NickName"> ... </string>
321 <string name="LastName"> ... </string>
322 <string name="FriendStatus"> ... </string>
323 <img name="Img"> ... </img>
330 <h4>deleteFriend</h4>
333 <Request class="friends" function ="deleteFriend">
334 <Params id="..."/>
337 <b>Response:</b> info message or error message.
345 <Request class="photos" function="createAlbum">
346 <Params id="...">
347 <string name="name"> ... </string>
348 <string name="description"> ... </string>
349 <string name="privacy">PRIVACY</string>
353 PRIVACY can have following values:
355 <li>SELF - created album will be available only for its owner; </li>
356 <li>ALL_FRIENDS - created album will be available for owner's friends;</li>
357 <li>FRIENDS_OF_FRIENDS - created album will be available only for owner's friends and their friends; </li>
358 <li>EVERYONE - created album will be available only for every user.</li>
360 <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>
362 <li><i>id</i> - optional, equals id of owner of current account by default </li>
363 <li><i>name</i> - optional, equals "no_name" by default</li>
364 <li><i>description</i> - optional </li>
368 <Response class="photos" function="createAlbum">
369 <Params id="...">
370 <string name="albumId"> ... </string>
375 <h4>getListAlbums</h4>
378 <Request class="photos" function="getListAlbums">
379 <Params id="..."/>
382 <p><i>id</i> - optional, equals id of owner of current account by default.</p>
385 <Response class="photos" function="getListAlbums">
387 <array name="albumList" quantity="..." ownerId="...">
388 <struct name="album" id="...">
389 <string name="title"> ... </string>
390 <string name="description"> ... </string>
391 <string name="thumbId"> ... </string>
392 <img name="Img"> ... </img>
393 <number name="created"> ... </number>
394 <number name="updated"> ... </number>
395 <number name="size"> ... </number>
396 <number name="canUpload"> ... </number>
402 <p><i>canUpload</i> - optional, if this parameter isn't set, it means that album is available for current user.</p>
407 <Request class="photos" function = "uploadPhoto">
409 <string name="albumId"> ... </string>
410 <string name="albumName"> ... </string>
411 <string name="albumPrivacy"> ... </string>
412 <string name="albumDescription"> ... </string>
413 <string name="file"> ... </string>
414 <string name="fileName"> ... </string>
415 <string name="description"> ... </string>
416 <string name="tags"> ... </string>
421 <li>There have to be only one of parameters <i>albumName</i> or <i>albumId</i> in request.</li>
422 <li>If <i>albumId</i> is set, photo is uploaded to this album.</li>
423 <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>
424 <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>
425 <li>Parameter <i>tags</i> can not be supported by some services.</li>
426 <li>Parameter <i>file</i> contains full path to file for sending.</li>
427 <li>Parameter <i>fileName</i> contains name of file for upload.</li>
431 <Response class="photos" function = "uploadPhoto">
433 <string name="albumId"> ... </string>
434 <string name="photoId"> ... </string>
439 <h4>getListPhotos</h4>
442 <Request class="photos" function = "getListPhotos">
443 <Params id="...">
444 <string name="albumId"> ... </string>
445 <number name="page"> ... </number>
446 <number name="pageSize"> ... </number>
451 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
452 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
453 <li><i>id</i> - user id (optional, equals id of owner of current account by default) </li>
457 <Response class="photos" function="getListPhotos">
459 <array name="photosList" page="..." pageSize="..." quantity="..." ownerId="..." albumId="...">
460 <struct name="photo" id="..."/>
461 <string name="urlSmall"> ... </string>
462 <string name="urlBig"> ... </string>
463 <string name="urlOrig"> ... </string>
464 <string name="description"> ... </string>
465 <number name="created"> ... </number>
472 <h4>getListUserPhotos</h4>
475 <Request class="photos" function = "getListUserPhotos">
476 <Params id="...">
477 <number name="page"> ... </number>
478 <number name="pageSize"> ... </number>
483 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
484 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
485 <li><i>id</i> - user id (optional, equals id of owner of current account by default) </li>
489 <Response class="photos" function="getListUserPhotos">
491 <array name="photosList" page="..." pageSize="..." quantity="...">
492 <struct name="photo" id="..."/>
493 <string name="ownerId"> ... </string>
494 <string name="albumId"> ... </string>
495 <string name="urlSmall"> ... </string>
496 <string name="urlBig"> ... </string>
497 <string name="urlOrig"> ... </string>
498 <string name="description"> ... </string>
499 <number name="created"> ... </number>
506 <h4>getListPhotoTags</h4>
509 <Request class="photos" function = "getListPhotoTags">
511 <string name="ownerId"> ... </string>
512 <string name="albumId"> ... </string>
513 <string name="photoId"> ... </string>
519 <Response class="photos" function="getListPhotoTags">
521 <array name="tagsList" quantity="..." ownerId="..." albumId="..." photoId="...">
522 <struct name="tag" id="..."/>
523 <string name="userId"> ... </string>
524 <string name="text"> ... </string>
525 <number name="created"> ... </number>
531 <p>Parameter <i>userId</i> is an id of user which is marked on photo (optional).</p>
533 <h4>getListFavoritePhotos</h4>
536 <Request class="photos" function = "getListFavoritePhotos">
537 <Params id="...">
538 <number name="page"> ... </number>
539 <number name="pageSize"> ... </number>
544 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
545 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
546 <li><i>id</i> - user id (optional, equals id of owner of current account by default) </li>
550 <Response class="photos" function="getListFavoritePhotos">
552 <array name="photosList" page="..." pageSize="..." quantity="...">
553 <struct name="photo" id="..."/>
554 <string name="ownerId"> ... </string>
555 <string name="albumId"> ... </string>
556 <string name="urlSmall"> ... </string>
557 <string name="urlBig"> ... </string>
558 <string name="urlOrig"> ... </string>
559 <string name="description"> ... </string>
560 <number name="created"> ... </number>
570 <Request class="photos" function = "getPhoto">
572 <string name="url"> ... </string>
573 <string name="path"> ... </string>
577 <b>Response:</b> info message or error message.
579 <h4>getListPhotoComments</h4>
582 <Request class="photos" function = "getListPhotoComments">
584 <string name="ownerId"> ... </string>
585 <string name="albumId"> ... </string>
586 <string name="photoId"> ... </string>
587 <number name="page"> ... </number>
588 <number name="pageSize"> ... </number>
593 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
594 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
598 <Response class="photos" function="getListPhotoComments">
600 <array name="commentsList" page="..." pageSize="..." quantity="..." ownerId="..." albumId="..." photoId="...">
601 <struct name="comment" id="..."/>
602 <string name="ParentId"> ... </string>
603 <string name="SenderId"> ... </string>
604 <string name="SenderName"> ... </string>
605 <string name="Time"> ... </string>
606 <string name="Text"> ... </string>
612 <p>Parameter <i>ParentId</i> is an id of previous comment, if there is such one (optional).</p>
614 <h4>sendPhotoComment</h4>
617 <Request class="photos" function="sendPhotoComment">
619 <string name="ownerId"> ... </string>
620 <string name="albumId"> ... </string>
621 <string name="photoId"> ... </string>
622 <string name="text"> ... </string>
626 <b>Response:</b> info message or error message.
631 <h4>getListOutboxMessages</h4>
634 <Request class="messages" function="getListOutboxMessages">
636 <number name="page"> ... </number>
637 <number name="pageSize"> ... </number>
638 <number name="timeOffset"> ... </number>
643 <li><i>page</i> - number of page that is requested (optional, positive integer, equals 1 by default)</li>
644 <li><i>pageSize</i> - page size (optional, positive integer, equals 100 by default)</li>
645 <li><i>timeOffset</i> - time offset for requested messages</li>
649 <Response class="messages" function = "getListOutboxMessages">
651 <array name="messageList" page="..." pageSize="..." quantity="...">
652 <struct name="message" id="...">
653 <string name="SenderId"> ... </string>
654 <string name="SenderName"> ... </string>
655 <array name="recipientList" quantity="...">
656 <struct name="recipient">
657 <string name="RecipientId"> ... </string>
658 <string name="RecipientName"> ... </string>
661 <string name="Time"> ... </string>
662 <string name="Title"> ... </string>
663 <string name="Text"> ... </string>
664 <string name="Status"> ... </string>
665 <attachment id="..." ownerId="..." type="...">
673 <p>Parameter <i>attachment</i> is optional, its content depends on attribute <i>type</i> and can have following values:</p>
675 <attachment id="..." ownerId="..." type="image">
676 <string name="name"> ... </string>
677 <string name="albumId"> ... </string>
678 <string name="urlSmall"> ... </string>
679 <string name="urlBig"> ... </string>
682 <attachment id="..." ownerId="..." type="video">
683 <string name="name"> ... </string>
684 <string name="url"> ... </string>
685 <number name="duration"> ... </number>
686 <string name="urlImage"> ... </string>
689 <attachment id="..." ownerId="..." type="audio">
690 <string name="name"> ... </string>
691 <string name="url"> ... </string>
692 <number name="duration"> ... </number>
695 <attachment id="..." ownerId="..." type="link">
696 <string name="name"> ... </string>
697 <string name="url"> ... </string>
698 <string name="urlImage"> ... </string>
701 <attachment id="..." ownerId="..." type="note">
702 <string name="name"> ... </string>
703 <string name="url"> ... </string>
712 <h4>getListAudio</h4>
715 <Request class="audio" function="getListAudio">
716 <Params id="...">
722 <Response class="audio" function="getListAudio">
723 <Params id="...">
724 <array name="audioList" quantity="..." ownerId="...">
725 <struct name="audio" id="...">
726 <string name="title"> ... </string>
727 <string name="artist"> ... </string>
728 <number name="duration"> ... </number>
729 <string name="audio"> ...url... </string>
739 <h4>getListVideo</h4>
742 <Request class="video" function="getListVideo">
743 <Params id="...">
749 <Response class="video" function="getListVideo">
751 <array name="videoList" quantity="..." ownerId="...">
752 <struct name="video" id="...">
753 <string name="title"> ... </string>
754 <string name="description"> ... </string>
755 <number name="duration"> ... </number>
756 <img name="Img"> ...url... </img>
757 <string name="link"> ...url... </string>
758 <string name="url"> ...url to player... </string>
769 <h3>Info and error messages</h3>
770 <h4>Error message format</h4>
772 <Response class="systemMessages" function = "errorMessage">
774 <string name="moduleName"> ... </string>
775 <string name="code"> ... </string>
776 <string name="text"> ... </string>
777 <string name="comment"> ... </string>
778 <string name="type">user/internal/service </string>
783 <h4>Info message format</h4>
785 <Response class="systemMessages" function = "infoMessage">
787 <string name="moduleName"> ... </string>
798 <td><table width="92%" border="0" align="right" cellpadding="0"
801 <td class="copybox"> MySocials Project © 2011</td>
806 <td height="10"> </td>