Topic

Topic

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

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

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

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

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

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

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

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

guest_new_topic

Function:

Function Name	Description	Level
guest_new_topic	guest post new topic to a particular forum	4

Input Parameters:

Name	Type	Required?	Description	Level
forum_id	String	yes		3
subject	byte[]	yes		3
text_body	byte[]	yes		3
username	byte[]	yes	Guest display name

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
timestamp	String		Timestamp of topic last reply