MySocials API
MySocials driver API
MySocials driver is provided as a shared library (libmsa<service_name>.so). Structure msa_module *d includes information about the driver (name, identifier, pointers to driver functions). This structure is filled during initialization of the driver.
Driver interface
Driver interface is described in file interface.h and consists of 4 functions:
- msa_module_init(struct msa_module* d) — driver initialization;
- msa_module_get_info(struct msa_module* d) — getting information about driver;
- msa_module->send(xmlDocPtr request, xmlDocPtr* response, const struct msa_module* info) — request sending and response receiveing;
- msa_module->shutdown(const struct msa_module*) - driver shutdown.
Driver initialization and shutting down
Driver initialization is performed by using msa_module_init(struct msa_module* d) function. Instance of structure which stores profile setting is created during initialization. Parameter d stores identifier of this instance.
Function msa_module->shutdown(const struct msa_module*) is used during program termination.
Interaction with driver
Function msa_module->send(xmlDocPtr request, xmlDocPtr* response, const struct msa_module* info) is used to perform requests to the driver.
Parameter request is a request in XML format. Description of structure of sending and receiveing data is described here.
Parameter response contains driver response in XML format.
Function msa_module_get_info(struct msa_module* d) is used to get information about driver (driver name and icon).
MySocials driver data structures
Here you can see description of data structures which are used by MySocials driver. These structures are declared in mysocials_driver.h file which is available for other applications from mysocials-dev package.
Enumerations
Error codes
enum error_type {
FAILURE, // Function finished with error
SUCCESS, // Function finished without error
ERROR_ALLOCATION_OF_MEMORY, // Allocation of memory
ERROR_NO_FUNCTION, // Defining function error
ERROR_INITIALIZATION_ALREADY_PASSED, // Re-initialization error
ERROR_IS_BUSY, // Module is busy
ERROR_SEND_DATA, // Data sending error
ERROR_PARSE_DATA // Data parsing error
}
Driver interface
MySocials driver interface described in msa_module structure. Some of the fields of this structure are filled before initialization by application (marked with **), the rest of it is filled during initialization.
struct msa_module {
gchar *id; // Identifier
gchar *name; // External driver name
gchar* driverName; // Driver name for system purposes (equals driver identifier)
gchar *pic; // Icon coded in base64
gchar *proxy; // **Proxy server address or NULL
gint port; // **Proxy server port
/* Pointer to function for processing requests.
Parameters:
xmlRequest — request in XML format
xmlResponse — response in XML format
info — structure with driver settings
Function returns SUCCESS in case without errors, otherwise FAILURE.
*/
error_type (*send)(char* xmlRequest, char** xmlResponse, struct msa_module *info)
/* Pointer to function for driver shutting down.
Parameters:
info — structure with driver settings
Function returns SUCCESS in case without errors, otherwise FAILURE.
*/
error_type (*shutdown)(struct msa_module* info);
}
Format of XML requests and responses
Common format of driver request and response
Request format
<Request class="" function="" noAuthorize="true">
<Params>
</Params>
</Request>
- noAuthorize - flag which forbids driver to call WebAuth (optional, set to false by default)
- class - class which includes called function
- function - name of the function
- Params - set of parameters, strictly defined for each function
Response format
<Response class="" function="" authorized="true" upload="..." download="...">
<Params>
</Params>
</Response>
- authorized - flag which indicates authorization during request performing (flag isn't set if error occurs during request performing)
- upload - number of bytes sent to server
- download - number of bytes received from server
Following classes are supported:
- settings: class for working with settings
- profile: class for receiving data about user's profile
- friends: class for receiving data about user's friends
- messages: class for receiving data about messages
- photos: class for working with photos
- audio: class for working with audio files
- video: class for working with video files
- news: class for working with news
Settings
getSettings
Request:
<Request class="settings" function="getSettings">
<Params/>
</Request>
Response:
<Response class="settings" function="getSettings">
<Params>
<string name="mid"> ... </string>
<string name="sid"> ... </string>
<string name="secret"> ... </string>
</Params>
</Response>
Content of Params tag depends on the driver. It is recommended to save content of Params tag and send it to setup function without any changes.
setSettings
Request:
<Request class="settings" function="setSettings">
<Params>
<string name="mid"> ... </string>
<string name="sid"> ... </string>
<string name="secret"> ... </string>
</Params>
</Request>
Params tag must contain data received from driver during getSettings request.
Response: info message or error message.
getListMethods
Request:
<Request class="settings" function="getListMethods">
<Params/>
</Request>
Response:
<Response class="settings" function="getListMethods">
<Params>
<string function="..." class="..."> ... </string>
<string function="..." class="..."> ... </string>
...
</Params>
</Response>
testConnection
Request:
<Request class="settings" function="testConnection">
<Params/>
</Request>
Response: info message or error message.
Profile
getProfile
Request:
<Request class="profile" function="getProfile">
<Params id="...">
</Request>
Attribute id is an id of user whose profile is needed to be received (optional, equals id of owner of current account by default).
Response:
<Response class="profile" function="getProfile">
<Params id="...">
<string name="FirstName"> ... </string>
<string name="NickName"> ... </string>
<string name="LastName"> ... </string>
<string name="Gender"> ... </string>
<string name="Birthday"> ... </string>
<string name="MobilePhone"> ... </string>
<string name="HomePhone"> ... </string>
<img name="Img"> ... </img>
<string name="CityName"> ... </string>
<string name="CountryName"> ... </string>
</Params>
</Response>
getBaseProfile
Request:
<Request class="profile" function="getBaseProfile">
<Params id="...">
</Request>
Attribute id is an id of user whose profile is needed to be received (optional, equals id of owner of current account by default).
Response:
<Response class="profile" function="getBaseProfile">
<Params id="...">
<string name="FirstName"> ... </string>
<string name="NickName"> ... </string>
<string name="LastName"> ... </string>
</Params>
</Response>
Friends
getListFriends
Request:
<Request class="friends" function="getListFriends">
<Params id="...">
<number name="page"> ... </number>
<number name="pageSize"> ... </number>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
- id - user id (optional, equals id of owner of current account by default)
Response:
<Response class="friends" function="getListFriends">
<Params id="...">
<array name="contactList" page="..." pageSize="..." quantity="...">
<struct name="contact" id="...">
<string name="FirstName"> ... </string>
<string name="NickName"> ... </string>
<string name="LastName"> ... </string>
<string name="FriendStatus"> ... </string>
<img name="Img"> ... </img>
</struct>
</array>
</Params>
</Response>
deleteFriend
Request:
<Request class="friends" function ="deleteFriend">
<Params id="..."/>
</Request>
Response: info message or error message.
Photos
createAlbum
Request:
<Request class="photos" function="createAlbum">
<Params id="...">
<string name="name"> ... </string>
<string name="description"> ... </string>
<string name="privacy">PRIVACY</string>
</Params>
</Request>
PRIVACY can have following values:
- SELF - created album will be available only for its owner;
- ALL_FRIENDS - created album will be available for owner's friends;
- FRIENDS_OF_FRIENDS - created album will be available only for owner's friends and their friends;
- EVERYONE - created album will be available only for every user.
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.
- id - optional, equals id of owner of current account by default
- name - optional, equals "no_name" by default
- description - optional
Response:
<Response class="photos" function="createAlbum">
<Params id="...">
<string name="albumId"> ... </string>
</Params>
</Response>
getListAlbums
Request:
<Request class="photos" function="getListAlbums">
<Params id="..."/>
</Request>
id - optional, equals id of owner of current account by default.
Response:
<Response class="photos" function="getListAlbums">
<Params>
<array name="albumList" quantity="..." ownerId="...">
<struct name="album" id="...">
<string name="title"> ... </string>
<string name="description"> ... </string>
<string name="thumbId"> ... </string>
<img name="Img"> ... </img>
<number name="created"> ... </number>
<number name="updated"> ... </number>
<number name="size"> ... </number>
<number name="canUpload"> ... </number>
</struct>
</array>
</Params>
</Response>
canUpload - optional, if this parameter isn't set, it means that album is available for current user.
uploadPhoto
Request:
<Request class="photos" function = "uploadPhoto">
<Params>
<string name="albumId"> ... </string>
<string name="albumName"> ... </string>
<string name="albumPrivacy"> ... </string>
<string name="albumDescription"> ... </string>
<string name="file"> ... </string>
<string name="fileName"> ... </string>
<string name="description"> ... </string>
<string name="tags"> ... </string>
</Params>
</Request>
- There have to be only one of parameters albumName or albumId in request.
- If albumId is set, photo is uploaded to this album.
- If albumId isn't specified, new album is created (with name albumName, description albumDescription and private settings albumPrivacy).
- If both parameters albumName and albumId aren't specified, driver returns error message or photo is uploaded to common album, which is available in some services.
- Parameter tags can not be supported by some services.
- Parameter file contains full path to file for sending.
- Parameter fileName contains name of file for upload.
Response:
<Response class="photos" function = "uploadPhoto">
<Params>
<string name="albumId"> ... </string>
<string name="photoId"> ... </string>
</Params>
</Response>
getListPhotos
Request:
<Request class="photos" function = "getListPhotos">
<Params id="...">
<string name="albumId"> ... </string>
<number name="page"> ... </number>
<number name="pageSize"> ... </number>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
- id - user id (optional, equals id of owner of current account by default)
Response:
<Response class="photos" function="getListPhotos">
<Params>
<array name="photosList" page="..." pageSize="..." quantity="..." ownerId="..." albumId="...">
<struct name="photo" id="..."/>
<string name="urlSmall"> ... </string>
<string name="urlBig"> ... </string>
<string name="urlOrig"> ... </string>
<string name="description"> ... </string>
<number name="created"> ... </number>
</struct>
</array>
</Params>
</Response>
getListUserPhotos
Request:
<Request class="photos" function = "getListUserPhotos">
<Params id="...">
<number name="page"> ... </number>
<number name="pageSize"> ... </number>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
- id - user id (optional, equals id of owner of current account by default)
Response:
<Response class="photos" function="getListUserPhotos">
<Params>
<array name="photosList" page="..." pageSize="..." quantity="...">
<struct name="photo" id="..."/>
<string name="ownerId"> ... </string>
<string name="albumId"> ... </string>
<string name="urlSmall"> ... </string>
<string name="urlBig"> ... </string>
<string name="urlOrig"> ... </string>
<string name="description"> ... </string>
<number name="created"> ... </number>
</struct>
</array>
</Params>
</Response>
getListPhotoTags
Request:
<Request class="photos" function = "getListPhotoTags">
<Params>
<string name="ownerId"> ... </string>
<string name="albumId"> ... </string>
<string name="photoId"> ... </string>
</Params>
</Request>
Response:
<Response class="photos" function="getListPhotoTags">
<Params>
<array name="tagsList" quantity="..." ownerId="..." albumId="..." photoId="...">
<struct name="tag" id="..."/>
<string name="userId"> ... </string>
<string name="text"> ... </string>
<number name="created"> ... </number>
</struct>
</array>
</Params>
</Response>
Parameter userId is an id of user which is marked on photo (optional).
getListFavoritePhotos
Request:
<Request class="photos" function = "getListFavoritePhotos">
<Params id="...">
<number name="page"> ... </number>
<number name="pageSize"> ... </number>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
- id - user id (optional, equals id of owner of current account by default)
Response:
<Response class="photos" function="getListFavoritePhotos">
<Params>
<array name="photosList" page="..." pageSize="..." quantity="...">
<struct name="photo" id="..."/>
<string name="ownerId"> ... </string>
<string name="albumId"> ... </string>
<string name="urlSmall"> ... </string>
<string name="urlBig"> ... </string>
<string name="urlOrig"> ... </string>
<string name="description"> ... </string>
<number name="created"> ... </number>
</struct>
</array>
</Params>
</Response>
getPhoto
Request:
<Request class="photos" function = "getPhoto">
<Params>
<string name="url"> ... </string>
<string name="path"> ... </string>
</Params>
</Request>
Response: info message or error message.
getListPhotoComments
Request:
<Request class="photos" function = "getListPhotoComments">
<Params>
<string name="ownerId"> ... </string>
<string name="albumId"> ... </string>
<string name="photoId"> ... </string>
<number name="page"> ... </number>
<number name="pageSize"> ... </number>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
Response:
<Response class="photos" function="getListPhotoComments">
<Params>
<array name="commentsList" page="..." pageSize="..." quantity="..." ownerId="..." albumId="..." photoId="...">
<struct name="comment" id="..."/>
<string name="ParentId"> ... </string>
<string name="SenderId"> ... </string>
<string name="SenderName"> ... </string>
<string name="Time"> ... </string>
<string name="Text"> ... </string>
</struct>
</array>
</Params>
</Response>
Parameter ParentId is an id of previous comment, if there is such one (optional).
sendPhotoComment
Request:
<Request class="photos" function="sendPhotoComment">
<Params>
<string name="ownerId"> ... </string>
<string name="albumId"> ... </string>
<string name="photoId"> ... </string>
<string name="text"> ... </string>
</Params>
</Request>
Response: info message or error message.
Messages
getListOutboxMessages
Request:
<Request class="messages" function="getListOutboxMessages">
<Params>
<number name="page"> ... </number>
<number name="pageSize"> ... </number>
<number name="timeOffset"> ... </number>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
- timeOffset - time offset for requested messages
Response:
<Response class="messages" function = "getListOutboxMessages">
<Params>
<array name="messageList" page="..." pageSize="..." quantity="...">
<struct name="message" id="...">
<string name="SenderId"> ... </string>
<string name="SenderName"> ... </string>
<array name="recipientList" quantity="...">
<struct name="recipient">
<string name="RecipientId"> ... </string>
<string name="RecipientName"> ... </string>
</struct>
</array>
<string name="Time"> ... </string>
<string name="Title"> ... </string>
<string name="Text"> ... </string>
<string name="Status"> ... </string>
<attachment id="..." ownerId="..." type="...">
...
</attachment>
</struct>
</array>
</Params>
</Response>
Parameter attachment is optional, its content depends on attribute type and can have following values:
<attachment id="..." ownerId="..." type="image">
<string name="name"> ... </string>
<string name="albumId"> ... </string>
<string name="urlSmall"> ... </string>
<string name="urlBig"> ... </string>
</attachment>
<attachment id="..." ownerId="..." type="video">
<string name="name"> ... </string>
<string name="url"> ... </string>
<number name="duration"> ... </number>
<string name="urlImage"> ... </string>
</attachment>
<attachment id="..." ownerId="..." type="audio">
<string name="name"> ... </string>
<string name="url"> ... </string>
<number name="duration"> ... </number>
</attachment>
<attachment id="..." ownerId="..." type="link">
<string name="name"> ... </string>
<string name="url"> ... </string>
<string name="urlImage"> ... </string>
</attachment>
<attachment id="..." ownerId="..." type="note">
<string name="name"> ... </string>
<string name="url"> ... </string>
</attachment>
getListInboxMessages
Request:
<Request class="messages" function="getListInboxMessages">
<Params>
<number name="page"></number>
<number name="pageSize"></number>
<number name="timeOffset"> ... </number>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
- timeOffset - time offset for requested news (optional)
Response:
<Response class="messages" function = "getListInboxMessages">
<Params>
<array name="messageList" page="..." pageSize="..." quantity="...">
<struct name="message" id="...">
<string name="SenderId"> ... </string>
<string name="SenderName"> ... </string>
<string name="Time"> ... </string>
<string name="Title"> ... </string>
<string name="Text"> ... </string>
<string name="Status"> ... </string>
<attachment id="..." ownerId="..." type="...">
...
</attachment>
</struct>
</array>
</Params>
</Response>
getListThreads
Request:
<Request class="messages" function="getListThreads">
<Params>
<number name="page"></number>
<number name="pageSize"></number>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
Response:
<Response class="messages" function = "getListThreads">
<Params>
<array name="threadList" page="..." pageSize="..." quantity="...">
<struct name="thread" id="...">
<number name="time"> ... </number>
<number name="size"> ... </number>
</struct>
</array>
</Params>
</Response>
getListThreadMessages
Request:
<Request class="messages" function="getListThreadMessages">
<Params>
<string name="threadId"></string>
<number name="page"></number>
<number name="pageSize"></number>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
Response:
<Response class="messages" function = "getListThreadMessages">
<Params>
<array name="messageList" threadId="..." page="..." pageSize="..." quantity="...">
<struct name="message" id="...">
<string name="SenderId"> ... </string>
<string name="SenderName"> ... </string>
<array name="recipientList" quantity="...">
<struct name="recipient">
<string name="RecipientId"> ... </string>
<string name="RecipientName"> ... </string>
</struct>
</array>
<string name="Time"> ... </string>
<string name="Title"> ... </string>
<string name="Text"> ... </string>
<string name="Status"> ... </string>
<attachment id="..." ownerId="..." type="...">
...
</attachment>
</struct>
</array>
</Params>
</Response>
- time - time of the last message in thread
- senderId and senderName - available only for inbox messages
- recipientList - available only for outbox messages
getTotalCountInbox
Request:
<Request class="messages" function = "getTotalCountInbox">
<Params/>
</Request>
Response:
<Response class="messages" function = "getTotalCountInbox">
<Params>
<string name="quantity"> ... </string>
</Params>
</Response>
getTotalCountOutbox
Request:
<Request class="messages" function = "getTotalCountOutbox">
<Params/>
</Request>
Response:
<Response class="messages" function = "getTotalCountOutbox">
<Params>
<string name="quantity"> ... </string>
</Params>
</Response>
getCountInboxByTime
Request:
<Request class="messages" function = "getCountInboxByTime">
<Params>
<number name="timeOffset"> ... </number>
</Params>
</Request>
Response:
<Response class="messages" function = "getCountInboxByTime">
<Params>
<string name="quantity"> ... </string>
</Params>
</Response>
getCountOutboxByTime
Request:
<Request class="messages" function = "getCountOutboxByTime">
<Params>
<number name="timeOffset"> ... </number>
</Params>
</Request>
Response:
<Response class="messages" function = "getCountOutboxByTime">
<Params>
<string name="quantity"> ... </string>
</Params>
</Response>
sendMessage
Request:
<Request class="messages" function = "sendMessage">
<Params id="...">
<string name="text"> ... </string>
<string name="title"> ... </string>
</Params>
</Request>
Response: info message or error message.
readMessage
Request:
<Request class="messages" function="readMessage">
<Params>
<string name="messageId"> ... </string>
</Params>
</Request>
Response: info message or error message.
deleteMessage
Request:
<Request class="messages" function="deleteMessage">
<Params>
<string name="messageId"> ... </string>
</Params>
</Request>
Response: info message or error message.
getListWallMessages
Request:
<Request class="messages" function="getListWallMessages">
<Params id="...">
<number name="page"></number>
<number name="pageSize"></number>
</Params>
</Request>
Response:
<Response class="messages" function = "getListWallMessages">
<Params id="...">
<array name="messageList" page="..." pageSize="..." quantity="...">
<struct name="message" id="...">
<string name="SenderId">... </string>
<string name="SenderName"> ... </string>
<string name="Time"> ... </string>
<string name="Text"> ... </string>
<attachment id="..." ownerId="..." type="...">
...
</attachment>
</struct>
</array>
</Params>
</Response>
Content of the attachment tag is the same as in class Messages.
getTotalCountWall
Request:
<Request class="messages" function = "getTotalCountWall">
<Params id="...">
</Params>
</Request>
Response:
<Response class="messages" function = "getTotalCountWall">
<Params>
<string name="quantity">123</string>
</Params>
</Response>
sendWallMessages
Request:
<Request class="messages" function = "sendWallMessage">
<Params id="...">
<string name="text">text of message</string>
</Params>
</Request>
Response: info message or error message.
deleteWallMessages
Request:
<Request class="messages" function="deleteWallMessage">
<Params>
<string name="messageId">...</string>
</Params>
</Request>
Response: info message or error message.
Audio
getListAudio
Request:
<Request class="audio" function="getListAudio">
<Params id="...">
</Params>
</Request>
Response:
<Response class="audio" function="getListAudio">
<Params id="...">
<array name="audioList" quantity="..." ownerId="...">
<struct name="audio" id="...">
<string name="title"> ... </string>
<string name="artist"> ... </string>
<number name="duration"> ... </number>
<string name="audio"> ...url... </string>
</struct>
</array>
</Params>
</Response>
getAudio
Request:
<Request class="audio" function="getAudio">
<Params id="vk...">
<string name="audioId">...</string>
</Params>
</Request>
Response:
<Response class="audio" function = "getAudio">
<Params>
<struct name="audio" id="vk..." ownerId="vk...">
<string name="title">...</string>
<string name="artist">...</string>
<number name="duration">...</number>
<string name="audio">...url...</string>
</struct>
</Params>
</Response>
Video
getListVideo
Request:
<Request class="video" function="getListVideo">
<Params id="...">
</Params>
</Request>
Response:
<Response class="video" function="getListVideo">
<Params>
<array name="videoList" quantity="..." ownerId="...">
<struct name="video" id="...">
<string name="title"> ... </string>
<string name="description"> ... </string>
<number name="duration"> ... </number>
<img name="Img"> ...url... </img>
<string name="link"> ...url... </string>
<string name="url"> ...url to player... </string>
</struct>
</array>
</Params>
</Response>
News
getListNews
Request:
<Request class="news" function="getListNews">
<Params>
<number name="page"> ... </number>
<number name="pageSize"> ... </number>
<number name="timeOffset"> ... </number>
<string name="newsType">TYPE</string>
</Params>
</Request>
- page - number of page that is requested (optional, positive integer, equals 1 by default)
- pageSize - page size (optional, positive integer, equals 100 by default)
- timeOffset - time offset for requested news (optional)
TYPE can have following values:
- photo: new friends' photos
- message: new wall messages
- comment: new comments to user's photos and comments to friends' photos that were commented by the user
- audio: new friends' audio
- video: new friends' video
- like: new "Like" marks
- tag: new mark on photos
- friend: new friends' friends
Response:
<Response class="news" function="getListNews">
<Params>
<array name="newsList" page="..." pageSize="..." quantity="..." newsType="TYPE">
<struct name="news">
<string name="authorId"> ... </string>
<string name="authorName"> ... </string>
<string name="text"> ... </string>
<number name="created"> ... </number>
<attachment id="..." ownerId="..." type="image/video/audio/link/note">
</attachment>
</struct>
</array>
</Params>
</Response>
authorName - news author name (optional).
Content of the attachment tag is the same as in class Messages.
Info and error messages
Error message format
<Response class="systemMessages" function = "errorMessage">
<Params>
<string name="moduleName"> ... </string>
<string name="code"> ... </string>
<string name="text"> ... </string>
<string name="comment"> ... </string>
<string name="type">user/internal/service </string>
</Params>
</Response>
Info message format
<Response class="systemMessages" function = "infoMessage">
<Params>
<string name="moduleName"> ... </string>
</Params>
</Response>
|