TDGSGL API

# Forum

Forum

This section describes the necessary API functions that allows Tapatalk app connects and retrieves necessary information to construct initial entry view of the app, plus various forum-structure related functions such as marking the entire forum as read.

# get_config

Function:

Function Name Description Level
get_config This function is always the first function to invoke when the app attempts to enter a specific forum. It returns configuration name/value pair for this forum system. There are two kind of name/value pairs. One is those based on some of the forum system configuration, and one is a simple name/value pairs declared in the config.txt file, usually located in mobiquo/conf/config.txt. E.g. the "guest_okay" is based on the forum system configuration. while the "api_level" is mobiquo

Input Parameters:

Name Type Required? Description Level

Output Parameters:

Name Type Required? Description Level
sys_version String Forum system version without forum type like 3.0.9 and 4.1.4
version String yes Tapatalk plugin version. Plugin developers: Set "version=dev" in order to get your development environment verified by the Tapatalk Network.
api_level String yes This value is to advise the app the API Level of this mobiquo plugin is currently at. Tapatalk API is currently at Level 3 ("api_level=3"). If this name/value pair is missing, the app would fall back to legacy mode for compatibility purpose. We plan to break the existing API into multiple levels so developer does not need to implement ALL the documented API for faster prototyping and improve time-to-market in phased basis. For plugin developer, please always return this key so the app will not fall back to legacy mode which may invoke undocumented functions.
is_open Boolean yes false: service is not available / true: service is available. Administrator can turn on/off by adjusting a value in a configuration file. If administrator set the entire forum system in maintenance mode, this should override this setting
guest_okay Boolean yes false: guest access is not allowed / true: guess access is allowed. Administrator can turn on/off by adjusting a value in the configuration file. If the forum system allows only login user, then the system value should over this setting
report_post String Return true to indicate the plugin support report_post function.
report_pm String Return true to indicate the plugin support report_pm function.
goto_post String Please refer to get_thread_by_post for more details. Only use this flag if the plugin is only API Level 3 but want to enable this feature. This flag will no longer needed in API Level 4 4
goto_unread String Please refer to get_thread_by_unread for more details. Only use this flag if the plugin is only API Level 3 but want to enable this feature. 4
mark_read String It should returns "1" or "0". If this key is missing, always assume "1". This is to indicate if the forum system support function mark_all_as_read . E.g. bbPress do not have read/unread function hence missing this functionality.
mark_forum String It should returns "1" or "0". If this key is missing, always assume "0". This is to indicate if function mark_all_as_read can accept a parameter as forum id to mark a specified forum as read. Please refer to mark_all_as_read for more details. Only use this flag if the plugin is only API Level 3 but want to enable this feature. 4
no_refresh_on_post String It should returns "1" or "0". If this key is missing, always assume "0". Please refer to reply_post and save_raw_post for more details. Only use this flag if the plugin is only API Level 3 but want to enable this feature. 4
subscribe_forum String It should returns "1" or "0". If this key is missing, always assume "1". This is to indicate this forum system supports "Sub-Forum Subscription" feature. Please refer to get_subscribed_forum for more details
get_latest_topic String It should returns "1" or "0". If this key is missing, always assume "0". This is to indicate this forum system does not support "get_latest_topic" function. Please refer to get_latest_topic for more details Please refer to get_latest_topic for more details 4
get_id_by_url String It should returns "1" or "0". If this key is missing, always assume "0". This is to indicate this forum system does not support get_id_by_url function. Please refer to get_id_by_url for more details 4
delete_reason String Return true if the plugin support a delete reason parameter. Please refer to m_delete_post and m_delete_topic .
m_approve String Returns "1" if supported. This is to indicate this forum system supports a centralized view to list all topics / posts pending to be approved. Please refer to m_get_moderate_topic for more details
m_delete String Returns "1" if supported. This is to indicate this forum system supports a centralized view to list all topics / posts that has been soft-deleted, allowing moderator to undelete topics / posts. Please refer to m_get_delete_topic for more details
m_report String Returns "1" if supported. This is to indicate this forum system supports a centralized view to list all topics / posts that have been reported by the users and need moderator attention. Please refer to m_get_report for more details
guest_search String Returns "1" if guest user can search in this forum without logging in. This is helpful as the app can enable search function under guest mode
anonymous String Return 1 if plugin support anonymous login. Check function login for details. 4
guest_whosonline String Return "1" if guest user can see who is currently online
searchid String Return "1" if search-related function like get_latest_topic / get_unread_topic / get_participated_topic / search_topic / search_post can support searchid pagination. 4
avatar String Return "1" if the plugin support get user avatar by avatar.php entry file. Please refer to avatar.php for more details 4
pm_load String Return "1" if get_box support pagination. 4
subscribe_load String Return "1" if get_subscribed_topic support pagination. 4
min_search_length Int Minimum string length for search_topic / search_post / search within forum.
inbox_stat String Return "1" if the plugin support pm and subscribed topic unread number since last check time. For more, please check function get_inbox_stat 4
multi_quote String Return 1 if the plugin support multi quote. Check more in get_quote_post 4
default_smilies String Forum default smilie set support. If set to "0" To indicate this forum has turned off default smilies support. 4
can_unread String It should returns "1" or "0". If this key is missing, always assume "1". If it set to "0", indicate this forum does not support Unread feature. E.g. bbPress 1.1 does not have Unread feature so app side need to hide all the related functions. 4
announcement String It should returns "1" or "0". If this key is missing, always assume "1". This instructs the app to hide/show the "Announcement" tab in topic view
emoji_support String Return 1 to indicate the plugin support emoji sent from app to be displayed on web browser
support_md5 String Return 1 to indicate the plugin support md5 password. Like in vbulletin plugin
support_sha1 String Return 1 to indicate the plugin support sha1 password. (To be implemented in app)
conversation String Return 1 if the plugin support conversation pm (currently only Xenforo plugin support conversation pm. IPB plugin should support it later.
get_forum String Return 1 if the plugin support function get_forum with two parameters for description control and sub forum id filter. 4
get_topic_status String Return 1 if the plugin support function get_topic_status 4
get_participated_forum String Return 1 if the plugin support function get_participated_forum 4
get_forum_status String Return 1 if the plugin support function get_forum_status 4
get_smilies String Return 1 if the plugin support function get_smilies 4
advanced_online_users String Return 1 if the plugin support get_online_users with forum and thread filter, and also pagination 4
mark_pm_unread String Return 1 if the plugin support function mark_pm_unread or mark_conversation_unread 4
mark_pm_read String Return 1 if the plugin support function mark_pm_read or mark_conversation_read
advanced_search String Return 1 if the plugin support function search 4
mass_subscribe String Return 1 if the plugin support id 'ALL' in unsubscribe_topic / unsubscribe_forum 4
user_id String Indicate the function get_participated_topic / get_user_info / get_user_topic / get_user_reply_post support request with user id. 4
advanced_delete String Return '1' if the plugin support both soft and hard delete.
mark_topic_read String Return 1 if the plugin support function mark_topic_read 4
first_unread String returns "0" if this forum system does not support First Unread feature. Assume "1" if missing. 4
alert String Indicate if the plugin support function get_alert
direct_unsubscribe String Indicate if user can unsubscribe_topic / unsubscribe_forum with subscribed id, not topic/forum id.
get_activity String Indicate if the plugin support function get_activity
prefix_edit String return 1 if plugin support prefix update in function m_rename_topic
push_type String Supported push type, joined with ','. Sample:ann,conv,pm,sub,like,thank,quote,newtopic,tag
ban_delete_type String Indicate if mod can delete user's post/topic when do ban and how the content will be deleted. Optional type: soft_delete, hard_delete, unapprove, none. 'none' means mod can not update user's post/topic status when do ban
anonymous_login String Indicate if plugin support anonymous login
advanced_edit String Indicate if the plugin support edit attachment.
search_user String Return 1 to indicate plugin support search_user function
user_recommended String Return 1 to indicate plugin support get_recommended_user function
inappreg String Indicate if account related functions are supported ot not. Including forget_password , update_password , update_email , register
sign_in String indicate function sign_in, prefetch_account, login status return was supported or not
ignore_user String Indicate if the plugin support function ignore_user
advanced_merge String It controls the third parameter('redirect') of function m_merge_topic .
advanced_move String It controls the third parameter('redirect') of function m_move_topic .
ban_expires String Return '1' if plugin support ban expires time in function m_ban_user
advanced_reg String Indicate if function register support custom field parameter.
close_report String Return '1' to indicate the plugin support m_close_report function.
get_contact String Return '1' to indicate the plugin support get_contact function.
ads_disabled_group String Group IDs which will not see ads in app. Separated by comma.
guest_group_id String Guest group ID
login_type String Indicate if forum system allow user login with username or email, or both would work. Valid value: username/email/both
get_topic_participants String Return 1 if the plugin support function get_topic_participants
get_member_list String Return 1 to indicate the plugin support get_member_list function.
m_get_inactive_users String Return 1 to indicate the plugin support m_get_inactive_users function.
m_approve_user String Return 1 to indicate the plugin support m_approve_user function.
user_bind_ttid String Return 1 to indicate the plugin support user_bind_ttid function.
update_profile String Return 1 to indicate the plugin support update_profile function.
guest_new_topic String Return 1 to indicate the plugin support guest_new_topic function.
guest_reply_post String Return 1 to indicate the plugin support guest_reply_post function.
remove_avatar String Return 1 to indicate the plugin support remove_avatar function.

# get_forum

Function:

Function Name Description Level
get_forum Return full forum in a nested tree structure. In API Level 3 no parameter required for this function and the sub-forum description. For Level 4, forum description is omitted unless "return_description" is set to true 3,4

Input Parameters:

Name Type Required? Description Level
return_description Boolean request to return sub-forum description. 4
forum_id String if this parmeter is presented, return only the immediate child of this forum. 4

Output Parameters:

Name Type Required? Description Level
Array of Hash table yes 3
forum_id String yes 3
forum_name byte[] 3
description byte[] Description of the forum. If required_description is set to true. 4
parent_id String yes parent's forum ID of this forum, returns -1 if this forum is the root forum 3
logo_url String returns the forum logo art-work URL (absolute URL). If any. 3
new_post Boolean returns true if this forum contains unread topic 3
is_protected Boolean returns true if this forum is password protected. The app side will call "login_forum" to get authorization before attempting to call get_topic the this forum. 3
is_subscribed Boolean returns true if the user has previously subscribed to this forum 3
can_subscribe Boolean returns false if the subscription feature is turned off 3
url String if it contains a url, it means this forum is just a link to other webpage 3
sub_only Boolean yes (true/false) identify whether this forum is only a placeholder ("Category" in vBulletin term) for sub-forums (sub_only = true), or can contains both topics and forums (sub_only = false) 3
child Array of Hash table if this forum is not a "leaf" forum, returns a list of child forum in an array of hash. This "child" key should return an array of hash. This entire structure can be nested. Client assume this is a leaf forum if this key is missing from the response 3,4

# get_participated_forum

Function:

Function Name Description Level
get_participated_forum return a list of sub-forum that user has previously participated in, order by the latest date of participation. 4

Input Parameters:

Name Type Required? Description Level

Output Parameters:

Name Type Required? Description Level
total_forums_num Int yes returns total number of subscribed forums 4
forums Array of Hash table yes returns an array of subscribed forums 4
forum_id String yes 4
forum_name byte[] yes 4
logo_url String an image URL to be displayed at the left hand side of the forum in the app. 4
is_protected Boolean return true if this forum is a protected forum. Please refer to "get_forum" for details description. 4
new_post Boolean return true if there is new posts in this forum. 4

# mark_all_as_read

Function:

Function Name Description Level
mark_all_as_read mark all the unread topics as read 3

Input Parameters:

Name Type Required? Description Level
forum_id String Specify the actual sub-forum to be marked as read, instead of marking the entire board as read. This parameters is only used when "mark_forum=1" returns in get_config, to indicate the plugin supports marking sub-forum read. 4

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully. 3
result_text Boolean Propose to add this field for error message returned from the server. 3

# login_forum

Function:

Function Name Description Level
login_forum Allows mobile client to access password protected sub-forum. It currently support only sub-forum at leaf level. If the password is valid, also return the updated cookies so the client will have access to the subsequent get_topic calls 3

Input Parameters:

Name Type Required? Description Level
forum_id String yes 3
password byte[] yes 3

Output Parameters:

Name Type Required? Description Level
result Boolean yes return true if the action is executed successfully. 3
result_text byte[] message to be displayed to users if there is complication during login. 3

# get_id_by_url

Function:

Function Name Description Level
get_id_by_url This new function is used to extract topic / post ID from a URL so an internal link can be open in app. Especially in SEO environment it is impossible for the app to detect the IDs from URL and hence requires server-side assistance. This function is used in conjunction with get_config that returns get_id_by_url = 1. 4

Input Parameters:

Name Type Required? Description Level
url String yes URL to be processed. 4

Output Parameters:

Name Type Required? Description Level
forum_id String 4
topic_id String 4
post_id String 4

# get_board_stat

Function:

Function Name Description Level
get_board_stat return board basic statistics data 3

Input Parameters:

Name Type Required? Description Level

Output Parameters:

Name Type Required? Description Level
total_threads Int yes 3
total_posts Int yes 3
total_members Int yes 3
active_members Int 3
total_online Int yes total online visitors including guests 3
guest_online Int yes 3

# get_forum_status

Function:

Function Name Description Level
get_forum_status Given an arrary of forum_id, returns their details and current status 4

Input Parameters:

Name Type Required? Description Level
forum_ids Array of String yes A list of forum_id as an array 4

Output Parameters:

Name Type Required? Description Level
forums Array of Hash table yes 4
forum_id String yes 4
forum_name byte[] yes 4
logo_url String 4
is_protected Boolean 4
new_post Boolean 4

# get_smilies

Function:

Function Name Description Level
get_smilies return forum customer smilies information 4

Input Parameters:

Name Type Required? Description Level

Output Parameters:

Name Type Required? Description Level
list Array of Hash table yes Hash of smilies category list. key name is category name and value is array of smilies in the category 4
[category name] Array of Hash table yes Smilies categoty name. If forum system does not support category for smilies, the name will be 'default' and there will be only one category in list 4
code byte[] yes smiley code like ':D' 4
url String yes smiley url(it may be relative path and need add forum root path to complete the url) 4
title byte[] smilies title (optional) 4

← User →