Home : API Home: Topic


Announcement: Ready to start? Try our PHP Starter-Kit for Plugin Developer, download the package from our Developer Support forum.


This section provides necessary functions related to topic creation and retrieval, including sticky topics, announcement, unread topics, participated topics and latest topics retrieval.


mark_topic_read

Top

Function:
Function Name Description Level
mark_topic_read mark unread topics as read 4

Input Parameters:
Name Type Required? Description Level
topic_id_array Array of String yes An array of string contains a list of topic Id to be marked as read. 4

Output Parameters:
Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully. 4
result_text byte[] Propose to add this field for error message returned from the server. 4


get_topic_status

Top

Function:
Function Name Description Level
get_topic_status Given an array of topic IDs, returns their status including unread status, number of reply, number of view and so on. A light-weight approach to retrieve certain information without pulling a list of unwanted data. 4

Input Parameters:
Name Type Required? Description Level
topic_id_array Array of String yes Given an array of topic IDs, returns their status including unread status, number of reply, number of view and so on. A light-weight approach to retrieve certain information without pulling a list of unwanted data. 4

Output Parameters:
Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully. 4
result_text byte[] Propose to add this field for error message returned from the server. 4
status Array of Hash table Return a list of topic status. Each item in the element is an Hashtable 4
topic_id String yes 4
is_subscribed Boolean return true if this thread has been subscribed by this user. 4
can_subscribe Boolean returns false if the subscription feature is turned off 4
is_closed Boolean return true if this thread has been closed. 4
last_reply_time Date yes dateTime.iso8601 format. If this topic has no reply, use the topic creation time. 4
timestamp String yes Timestamp of topic last reply
new_post Boolean yes return true if this topic contains new post since user last login 4
reply_number Int yes total number of reply in this topic. If this is no reply in this return, return 0. 4
view_number Int yes total number of view in this topic 4


new_topic

Top

Function:
Function Name Description Level
new_topic post new topic to a particular forum 3

Input Parameters:
Name Type Required? Description Level
forum_id String yes 3
subject byte[] yes 3
text_body byte[] yes 3
prefix_id String prefix ID that user has selected. List of prefixes are returned from "get_topic" method. 3
attachment_id_array Array of String List of attachment ID that come along with this topic creation. If this parameter is supplied, the previous parameter (parfix_id) should also be provided with null value.
group_id String required when attachment_id_array is specified

Output Parameters:
Name Type Required? Description Level
result String yes return true if the action is executed successfully. 3
result_text byte[] 3
topic_id String yes the newly generated topic ID for this new topic. 3
state Int yes 1 = post is success but need moderation. Otherwise no need to return this key. 3


get_topic

Top

Function:
Function Name Description Level
get_topic Returns a list of topics under a specific forum. It can also return sticky topics and announcement, given the "mode" parameter is provided. 3,4

Input Parameters:
Name Type Required? Description Level
forum_id String yes 3
start_num Int For pagination. If start_num = 0 & last_num = 9, it returns first 10 topics from the forum, sorted by date (last-in-first-out). If both are not presented, return first 20 topics. if start_num = 0 and last_num = 0, return the first topic only. If last_num - start_num > 50, returns only first 50 topics starting from start_num 3
last_num Int See above. 3
mode String if mode = "TOP", returns sticky topics, if mode = "ANN", returns "Announcement" topics only, otherwise returns standard topics. 3

Output Parameters:
Name Type Required? Description Level
total_topic_num Int yes Total number of topics in this forum. If this forum has no topic, it returns 0, and the "topics" key returns return null 3
forum_id String yes 3
forum_name byte[] yes 3
can_post Boolean return false if user cannot create new topic in this forum 3
unread_sticky_count Int Add a "unread_sticky_count" and "unread_announce_count" integer value in get_topic first level Hash-table to indicate users there are unread stickies topics and announcement in this sub-forum. This allow the app to show a unread badge when entering a sub-forum. 4
unread_announce_count Int Add a "unread_sticky_count" and "unread_announce_count" integer value in get_topic first level Hash-table to indicate users there are unread stickies topics and announcement in this sub-forum. This allow the app to show a unread badge when entering a sub-forum. 4
can_subscribe Boolean return true if current user can subscribe this forum. Default as true for member. 4
is_subscribed Boolean return true if this forum was subscribed by current user 4
require_prefix Boolean This is used in conjunction with existing "prefixes" in get_topic function, to indicate whether users need to select a prefix mandatory. If this field is missing, assuming mandatory. 4
prefixes Array of Hash table yes if this is not empty, it contains a list of prefixes, it indicates user need to enter prefix in order to create a new topic successfully 3
prefix_id String yes 3
prefix_display_name byte[] yes 3
topics Array of Hash table Returns a list of topic in an array, each topic is in Hash Table format. Returns null if total_topic_num = 0 3
forum_id String yes 3
topic_id String yes 3
topic_title byte[] yes Remove all BBCode in title 3
prefix byte[] Prefix name of current topic 4
topic_author_id String yes 4
topic_author_name byte[] yes 3
is_subscribed Boolean return true if this thread has been subscribed by this user. 3
can_subscribe Boolean returns false if the subscription feature is turned off 3
is_closed Boolean return true if this thread has been closed. 3
icon_url String Return topic author avatar URL 3
timestamp String yes Timestamp of topic last reply
last_reply_time Date yes dateTime.iso8601 format. If this topic has no reply, use the topic creation time. 3
reply_number Int yes total number of reply in this topic. If this is no reply in this return, return 0. 3
new_post Boolean yes return true if this topic contains new post since user last login 3
view_number Int yes total number of view in this topic 3
short_content byte[] Characters display rules (should follow this sequence): 1) Remove all BBCode except [ur], [img]. 2) Convert "[url http://...]http://…..[/url]" to "[url]". 3) Convert "[img]http://…..[/img]" to "[img]". 4) Remove "Last edited by..." tag at the end. 5) Remove all non-displayable characters (e.g. \n, \t, etc). 6) Remove all whitespace, /n and /r at the beginning and ending of the content. 7) return only first 200 characters 3
participated_uids Array of String Return a list of uids of the users who participated in this topic. It does not need to return all the uids of whoever participated, instead returns not more than 10, preferrably ordered by the "importance" - it can be determined by the number of posts the user contributed to this topic etc. Plugin should check HTTP Header "Mobiquoid". If it is ="11", return this key, otherwise do not return it. 4
is_moved Boolean Indicate if this is a moved topic
is_merged Boolean Indicate if this is a topic merged into another topic
real_topic_id String If this topic is a merged of moved topic, this key will include the real topic id


get_unread_topic

Top

Function:
Function Name Description Level
get_unread_topic Returns a list of unread topics ordered by date. 3,4

Input Parameters:
Name Type Required? Description Level
start_num Int For pagination. If start_num = 0 & last_num = 9, it returns first 10 posts from the topic, sorted by date (last-in-first-out). If both are not presented, return first 20 posts. if start_num = 0 and last_num = 0, return the first post only, and so on (e.g. 1,1; 2,2). If start_num smaller than last_num returns null. If last_num - start_num > 50, returns only first 50 posts starting from start_num 3
last_num Int 3
search_id String for caching and for pagination support
filters Array of Hash table A set of filtering rules to filter the search result. E.g. user can specify only to display topics under certain sub-forums, or can exclude topis from certain sub-forums. Format of the filters: "only_in" = { array of sub-forum ID }. "not_in" = {array of sub-forum ID}. 4

Output Parameters:
Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully. 3
result_text byte[] 3
search_id String return the search id so the app can send the same id back to the server for pagination support
total_topic_num Int yes total number of unread topics 3
topics Array of Hash table yes an array contains a list of unread topics 3
forum_id String yes 3
forum_name byte[] yes 3
topic_id String yes 3
topic_title byte[] yes Remove all BBCode in title 3
prefix byte[] 4
post_author_name byte[] yes return display name if it has in API level 4 3,4
post_author_id Int yes 4
is_subscribed Boolean return true if this thread has been subscribed by this user. 3
can_subscribe Boolean returns false if the subscription feature is turned off 3
is_closed Boolean return true if this thread has been closed. 3
icon_url String Return the last reply author avatar URL 3
participated_uids Array of String Return a list of uids of the users who participated in this topic. It does not need to return all the uids of whoever participated, instead returns not more than 10, preferrably ordered by the "importance" - it can be determined by the number of posts the user contributed to this topic etc. Plugin should check HTTP Header "Mobiquoid". If it is ="11", return this key, otherwise do not return it. 4
timestamp String yes Timestamp of topic last reply
post_time Date yes dateTime.iso8601 format. If this topic has no reply, use the topic creation time. 3
reply_number Int yes total number of reply in this topic. If this is no reply in this return, return 0. 3
new_post Boolean yes return true if this topic contains new post since user last login 3
view_number Int yes total number of view in this topic 3
short_content byte[] Characters display rules (should follow this sequence): 1) Remove all BBCode except [ur], [img]. 2) Convert "[url http://...]http://…..[/url]" to "[url]". 3) Convert "[img]http://…..[/img]" to "[img]". 4) Remove "Last edited by..." tag at the end. 5) Remove all non-displayable characters (e.g. \n, \t, etc). 6) Remove all whitespace, /n and /r at the beginning and ending of the content. 7) return only first 200 characters 3


get_participated_topic

Top

Function:
Function Name Description Level
get_participated_topic Returns a list of topics that either the user has previously replied to, or is the original topic creator, ordered by date. 3,4

Input Parameters:
Name Type Required? Description Level
user_name byte[] yes Ability to return a list of participated topics of a particular user. 3
start_num Int yes For pagination. If start_num = 0 & last_num = 9, it returns first 10 posts from the topic, sorted by date (last-in-first-out). If both are not presented, return first 20 posts. if start_num = 0 and last_num = 0, return the first post only, and so on (e.g. 1,1; 2,2). If start_num smaller than last_num returns null. If last_num - start_num > 50, returns only first 50 posts starting from start_num 3
last_num Int yes 3
search_id String for caching and for pagination support
user_id String yes Not required in Level 3. 4

Output Parameters:
Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully. 3
result_text byte[] 3
search_id String return the search id so the app can send the same id back to the server for pagination support
total_topic_num Int yes total number of participated topics 3
total_unread_num Int yes total number of participated topics that is currently unread. 4
topics Array of Hash table yes an array contains a list of participated topics 3
forum_id String yes 3
forum_name byte[] yes 3
topic_id String yes 3
topic_title byte[] yes Remove all BBCode in title 3
prefix byte[] 4
post_author_id String yes 4
post_author_name byte[] yes 3
is_subscribed Boolean return true if this thread has been subscribed by this user. 3
can_subscribe Boolean returns false if the subscription feature is turned off 3
is_closed Boolean return true if this thread has been closed. 3
icon_url String Return the last reply author avatar URL 3
participated_uids Array of String Return a list of uids of the users who participated in this topic. It does not need to return all the uids of whoever participated, instead returns not more than 10, preferrably ordered by the "importance" - it can be determined by the number of posts the user contributed to this topic etc. Plugin should check HTTP Header "Mobiquoid". If it is ="11", return this key, otherwise do not return it. 4
post_time Date yes dateTime.iso8601 format. If this topic has no reply, use the topic creation time. 3
timestamp String yes Timestamp of topic last reply
reply_number Int yes total number of reply in this topic. If this is no reply in this return, return 0. 3
new_post Boolean yes return true if this topic contains new post since user last login 3
view_number Int total number of view in this topic 3
short_content byte[] Characters display rules (should follow this sequence): 1) Remove all BBCode except [ur], [img]. 2) Convert "[url http://...]http://…..[/url]" to "[url]". 3) Convert "[img]http://…..[/img]" to "[img]". 4) Remove "Last edited by..." tag at the end. 5) Remove all non-displayable characters (e.g. \n, \t, etc). 6) Remove all whitespace, /n and /r at the beginning and ending of the content. 7) return only first 200 characters 3


get_latest_topic

Top

Function:
Function Name Description Level
get_latest_topic Returns a list of latest topics ordered by date. This is the replacement function of get_new_topic in API Level 3. This function will be invoked instead of get_new_topic if get_config returns "get_latest_topic=1" 4

Input Parameters:
Name Type Required? Description Level
start_num Int yes For pagination. If start_num = 0 & last_num = 9, it returns first 10 posts from the topic, sorted by date (last-in-first-out). If both are not presented, return first 20 posts. if start_num = 0 and last_num = 0, return the first post only, and so on (e.g. 1,1; 2,2). If start_num smaller than last_num returns null. If last_num - start_num > 50, returns only first 50 posts starting from start_num
last_num Int yes
search_id String for caching and for pagination support 4
filters Array of Hash table A set of filtering rules to filter the search result. E.g. user can specify only to display topics under certain sub-forums, or can exclude topis from certain sub-forums. Format of the filters: "only_in" = { array of sub-forum ID }. "not_in" = {array of sub-forum ID}. 4

Output Parameters:
Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully. 3
result_text byte[] para_description 3
total_topic_num Int yes total number of latest topics 4
search_id String return the search id so the app can send the same id back to the server for pagination support
topics Array of Hash table an array contains a list of topics in request range 4
forum_id String yes 4
forum_name byte[] yes 4
topic_id String yes 4
topic_title byte[] yes Remove all BBCode in title 4
prefix byte[] 4
post_author_name byte[] yes 4
post_author_id String yes 4
is_subscribed Boolean return true if this thread has been subscribed by this user. 4
can_subscribe Boolean yes returns false if the subscription feature is turned off 4
is_closed Boolean return true if this thread has been closed. 4
icon_url String Return the last reply author avatar URL 4
participated_uids Array of String Return a list of uids of the users who participated in this topic. It does not need to return all the uids of whoever participated, instead returns not more than 10, preferrably ordered by the "importance" - it can be determined by the number of posts the user contributed to this topic etc. Plugin should check HTTP Header "Mobiquoid". If it is ="11", return this key, otherwise do not return it. 4
post_time Date yes dateTime.iso8601 format. If this topic has no reply, use the topic creation time. 4
timestamp String yes Timestamp of topic last reply
reply_number Int yes total number of reply in this topic. If this is no reply in this return, return 0. 4
new_post Boolean yes return true if this topic contains new post since user last login 4
view_number Int yes total number of view in this topic 4
short_content byte[] Characters display rules (should follow this sequence): 1) Remove all BBCode except [ur], [img]. 2) Convert "[url http://...]http://…..[/url]" to "[url]". 3) Convert "[img]http://…..[/img]" to "[img]". 4) Remove "Last edited by..." tag at the end. 5) Remove all non-displayable characters (e.g. \n, \t, etc). 6) Remove all whitespace, /n and /r at the beginning and ending of the content. 7) return only first 200 characters 4


Top

Home : API Home: Topic