Merge pull request #4127 from Rudloff/feature/phpdoc

Add missing doc in api.php
This commit is contained in:
Hypolite Petovan 2017-12-24 09:54:19 -05:00 committed by GitHub
commit 3a3a690495
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -1,8 +1,8 @@
<?php <?php
/** /**
* @file include/api.php
* Friendica implementation of statusnet/twitter API * Friendica implementation of statusnet/twitter API
* *
* @file include/api.php
* @todo Automatically detect if incoming data is HTML or BBCode * @todo Automatically detect if incoming data is HTML or BBCode
*/ */
use Friendica\App; use Friendica\App;
@ -55,11 +55,11 @@ $API = array();
$called_api = null; $called_api = null;
/** /**
* @brief Auth API user
*
* It is not sufficient to use local_user() to check whether someone is allowed to use the API, * It is not sufficient to use local_user() to check whether someone is allowed to use the API,
* because this will open CSRF holes (just embed an image with src=friendicasite.com/api/statuses/update?status=CSRF * because this will open CSRF holes (just embed an image with src=friendicasite.com/api/statuses/update?status=CSRF
* into a page, and visitors will post something without noticing it). * into a page, and visitors will post something without noticing it).
*
* @brief Auth API user
*/ */
function api_user() function api_user()
{ {
@ -71,13 +71,13 @@ function api_user()
} }
/** /**
* @brief Get source name from API client
*
* Clients can send 'source' parameter to be show in post metadata * Clients can send 'source' parameter to be show in post metadata
* as "sent via <source>". * as "sent via <source>".
* Some clients doesn't send a source param, we support ones we know * Some clients doesn't send a source param, we support ones we know
* (only Twidere, atm) * (only Twidere, atm)
* *
* @brief Get source name from API client
*
* @return string * @return string
* Client source name, default to "api" if unset/unknown * Client source name, default to "api" if unset/unknown
*/ */
@ -110,9 +110,9 @@ function api_date($str)
} }
/** /**
* @brief Register API endpoint * Register a function to be the endpoint for defined API path.
* *
* Register a function to be the endpont for defined API path. * @brief Register API endpoint
* *
* @param string $path API URL path, relative to System::baseUrl() * @param string $path API URL path, relative to System::baseUrl()
* @param string $func Function name to call on path request * @param string $func Function name to call on path request
@ -142,11 +142,11 @@ function api_register_func($path, $func, $auth = false, $method = API_METHOD_ANY
} }
/** /**
* @brief Login API user
*
* Log in user via OAuth1 or Simple HTTP Auth. * Log in user via OAuth1 or Simple HTTP Auth.
* Simple Auth allow username in form of <pre>user@server</pre>, ignoring server part * Simple Auth allow username in form of <pre>user@server</pre>, ignoring server part
* *
* @brief Login API user
*
* @param object $a App * @param object $a App
* @hook 'authenticate' * @hook 'authenticate'
* array $addon_auth * array $addon_auth
@ -242,12 +242,12 @@ function api_login(App $a)
} }
/** /**
* @brief Check HTTP method of called API
*
* API endpoints can define which HTTP method to accept when called. * API endpoints can define which HTTP method to accept when called.
* This function check the current HTTP method agains endpoint * This function check the current HTTP method agains endpoint
* registered method. * registered method.
* *
* @brief Check HTTP method of called API
*
* @param string $method Required methods, uppercase, separated by comma * @param string $method Required methods, uppercase, separated by comma
* @return bool * @return bool
*/ */
@ -260,10 +260,10 @@ function api_check_method($method)
} }
/** /**
* @brief Main API entry point
*
* Authenticate user, call registered API function, set HTTP headers * Authenticate user, call registered API function, set HTTP headers
* *
* @brief Main API entry point
*
* @param object $a App * @param object $a App
* @return string API call result * @return string API call result
*/ */
@ -972,7 +972,9 @@ function api_format_data($root_element, $type, $data)
/** /**
* Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; * Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful;
* returns a 401 status code and an error message if not. * returns a 401 status code and an error message if not.
* http://developer.twitter.com/doc/get/account/verify_credentials * @see https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials
*
* @param string $type Return type (atom, rss, xml, json)
*/ */
function api_account_verify_credentials($type) function api_account_verify_credentials($type)
{ {
@ -1018,6 +1020,8 @@ api_register_func('api/account/verify_credentials', 'api_account_verify_credenti
/** /**
* Get data from $_POST or $_GET * Get data from $_POST or $_GET
*
* @param string $k
*/ */
function requestdata($k) function requestdata($k)
{ {
@ -1030,7 +1034,13 @@ function requestdata($k)
return null; return null;
} }
/*Waitman Gobble Mod*/ /**
* Waitman Gobble Mod
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_statuses_mediap($type) function api_statuses_mediap($type)
{ {
$a = get_app(); $a = get_app();
@ -1074,6 +1084,14 @@ function api_statuses_mediap($type)
/// @TODO move this to top of file or somewhere better! /// @TODO move this to top of file or somewhere better!
api_register_func('api/statuses/mediap', 'api_statuses_mediap', true, API_METHOD_POST); api_register_func('api/statuses/mediap', 'api_statuses_mediap', true, API_METHOD_POST);
/**
* Updates the users current status.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
* @see https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update
*/
function api_statuses_update($type) function api_statuses_update($type)
{ {
@ -1249,6 +1267,14 @@ function api_statuses_update($type)
api_register_func('api/statuses/update', 'api_statuses_update', true, API_METHOD_POST); api_register_func('api/statuses/update', 'api_statuses_update', true, API_METHOD_POST);
api_register_func('api/statuses/update_with_media', 'api_statuses_update', true, API_METHOD_POST); api_register_func('api/statuses/update_with_media', 'api_statuses_update', true, API_METHOD_POST);
/**
* Uploads an image to Friendica.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array
* @see https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload
*/
function api_media_upload($type) function api_media_upload($type)
{ {
$a = get_app(); $a = get_app();
@ -1287,6 +1313,12 @@ function api_media_upload($type)
/// @TODO move to top of file or somwhere better /// @TODO move to top of file or somwhere better
api_register_func('api/media/upload', 'api_media_upload', true, API_METHOD_POST); api_register_func('api/media/upload', 'api_media_upload', true, API_METHOD_POST);
/**
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_status_show($type) function api_status_show($type)
{ {
$a = get_app(); $a = get_app();
@ -1391,7 +1423,9 @@ function api_status_show($type)
/** /**
* Returns extended information of a given user, specified by ID or screen name as per the required id parameter. * Returns extended information of a given user, specified by ID or screen name as per the required id parameter.
* The author's most recent status will be returned inline. * The author's most recent status will be returned inline.
* http://developer.twitter.com/doc/get/users/show *
* @param string $type Return type (atom, rss, xml, json)
* @see https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-show
*/ */
function api_users_show($type) function api_users_show($type)
{ {
@ -1477,6 +1511,14 @@ function api_users_show($type)
api_register_func('api/users/show', 'api_users_show'); api_register_func('api/users/show', 'api_users_show');
api_register_func('api/externalprofile/show', 'api_users_show'); api_register_func('api/externalprofile/show', 'api_users_show');
/**
* Search a public user account.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
* @see https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search
*/
function api_users_search($type) function api_users_search($type)
{ {
$a = get_app(); $a = get_app();
@ -1607,11 +1649,14 @@ api_register_func('api/search/tweets', 'api_search', true);
api_register_func('api/search', 'api_search', true); api_register_func('api/search', 'api_search', true);
/** /**
* Returns the most recent statuses posted by the user and the users they follow.
* *
* http://developer.twitter.com/doc/get/statuses/home_timeline * @see https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-home_timeline
* *
* TODO: Optional parameters * @param string $type Return type (atom, rss, xml, json)
* TODO: Add reply info *
* @todo Optional parameters
* @todo Add reply info
*/ */
function api_statuses_home_timeline($type) function api_statuses_home_timeline($type)
{ {
@ -1708,6 +1753,13 @@ function api_statuses_home_timeline($type)
api_register_func('api/statuses/home_timeline', 'api_statuses_home_timeline', true); api_register_func('api/statuses/home_timeline', 'api_statuses_home_timeline', true);
api_register_func('api/statuses/friends_timeline', 'api_statuses_home_timeline', true); api_register_func('api/statuses/friends_timeline', 'api_statuses_home_timeline', true);
/**
* Returns the most recent statuses from public users.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_statuses_public_timeline($type) function api_statuses_public_timeline($type)
{ {
$a = get_app(); $a = get_app();
@ -1808,6 +1860,8 @@ function api_statuses_public_timeline($type)
api_register_func('api/statuses/public_timeline', 'api_statuses_public_timeline', true); api_register_func('api/statuses/public_timeline', 'api_statuses_public_timeline', true);
/** /**
* Returns the most recent statuses posted by users this node knows about.
*
* @brief Returns the list of public federated posts this node knows about * @brief Returns the list of public federated posts this node knows about
* *
* @param string $type Return format: json, xml, atom, rss * @param string $type Return format: json, xml, atom, rss
@ -1878,7 +1932,11 @@ function api_statuses_networkpublic_timeline($type)
api_register_func('api/statuses/networkpublic_timeline', 'api_statuses_networkpublic_timeline', true); api_register_func('api/statuses/networkpublic_timeline', 'api_statuses_networkpublic_timeline', true);
/** /**
* @TODO nothing to say? * Returns a single status.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @see https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-show-id
*/ */
function api_statuses_show($type) function api_statuses_show($type)
{ {
@ -1949,7 +2007,10 @@ function api_statuses_show($type)
api_register_func('api/statuses/show', 'api_statuses_show', true); api_register_func('api/statuses/show', 'api_statuses_show', true);
/** /**
* @TODO nothing to say? *
* @param string $type Return type (atom, rss, xml, json)
*
* @todo nothing to say?
*/ */
function api_conversation_show($type) function api_conversation_show($type)
{ {
@ -2036,7 +2097,11 @@ api_register_func('api/conversation/show', 'api_conversation_show', true);
api_register_func('api/statusnet/conversation', 'api_conversation_show', true); api_register_func('api/statusnet/conversation', 'api_conversation_show', true);
/** /**
* @TODO nothing to say? * Repeats a status.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @see https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-retweet-id
*/ */
function api_statuses_repeat($type) function api_statuses_repeat($type)
{ {
@ -2114,7 +2179,11 @@ function api_statuses_repeat($type)
api_register_func('api/statuses/retweet', 'api_statuses_repeat', true, API_METHOD_POST); api_register_func('api/statuses/retweet', 'api_statuses_repeat', true, API_METHOD_POST);
/** /**
* @TODO nothing to say? * Destroys a specific status.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @see https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-destroy-id
*/ */
function api_statuses_destroy($type) function api_statuses_destroy($type)
{ {
@ -2151,8 +2220,11 @@ function api_statuses_destroy($type)
api_register_func('api/statuses/destroy', 'api_statuses_destroy', true, API_METHOD_DELETE); api_register_func('api/statuses/destroy', 'api_statuses_destroy', true, API_METHOD_DELETE);
/** /**
* @TODO Nothing more than an URL to say? * Returns the most recent mentions.
* http://developer.twitter.com/doc/get/statuses/mentions *
* @param string $type Return type (atom, rss, xml, json)
*
* @see http://developer.twitter.com/doc/get/statuses/mentions
*/ */
function api_statuses_mentions($type) function api_statuses_mentions($type)
{ {
@ -2238,11 +2310,14 @@ api_register_func('api/statuses/mentions', 'api_statuses_mentions', true);
api_register_func('api/statuses/replies', 'api_statuses_mentions', true); api_register_func('api/statuses/replies', 'api_statuses_mentions', true);
/** /**
* Returns the most recent statuses posted by the user.
*
* @brief Returns a user's public timeline * @brief Returns a user's public timeline
* *
* @param string $type Either "json" or "xml" * @param string $type Either "json" or "xml"
* @return string|array * @return string|array
* @throws ForbiddenException * @throws ForbiddenException
* @see https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-user_timeline
*/ */
function api_statuses_user_timeline($type) function api_statuses_user_timeline($type)
{ {
@ -2330,10 +2405,12 @@ function api_statuses_user_timeline($type)
api_register_func('api/statuses/user_timeline', 'api_statuses_user_timeline', true); api_register_func('api/statuses/user_timeline', 'api_statuses_user_timeline', true);
/** /**
* Star/unstar an item * Star/unstar an item.
* param: id : id of the item * param: id : id of the item
* *
* api v1 : https://web.archive.org/web/20131019055350/https://dev.twitter.com/docs/api/1/post/favorites/create/%3Aid * @param string $type Return type (atom, rss, xml, json)
*
* @see https://web.archive.org/web/20131019055350/https://dev.twitter.com/docs/api/1/post/favorites/create/%3Aid
*/ */
function api_favorites_create_destroy($type) function api_favorites_create_destroy($type)
{ {
@ -2405,6 +2482,13 @@ function api_favorites_create_destroy($type)
api_register_func('api/favorites/create', 'api_favorites_create_destroy', true, API_METHOD_POST); api_register_func('api/favorites/create', 'api_favorites_create_destroy', true, API_METHOD_POST);
api_register_func('api/favorites/destroy', 'api_favorites_create_destroy', true, API_METHOD_DELETE); api_register_func('api/favorites/destroy', 'api_favorites_create_destroy', true, API_METHOD_DELETE);
/**
* Returns the most recent favorite statuses.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return string|array
*/
function api_favorites($type) function api_favorites($type)
{ {
global $called_api; global $called_api;
@ -2479,6 +2563,14 @@ function api_favorites($type)
/// @TODO move to top of file or somwhere better /// @TODO move to top of file or somwhere better
api_register_func('api/favorites', 'api_favorites', true); api_register_func('api/favorites', 'api_favorites', true);
/**
*
* @param array $item
* @param array $recipient
* @param array $sender
*
* @return array
*/
function api_format_messages($item, $recipient, $sender) function api_format_messages($item, $recipient, $sender)
{ {
// standard meta information // standard meta information
@ -2523,6 +2615,12 @@ function api_format_messages($item, $recipient, $sender)
return $ret; return $ret;
} }
/**
*
* @param array $item
*
* @return array
*/
function api_convert_item($item) function api_convert_item($item)
{ {
$body = $item['body']; $body = $item['body'];
@ -2592,6 +2690,12 @@ function api_convert_item($item)
); );
} }
/**
*
* @param string $body
*
* @return array
*/
function api_get_attachments(&$body) function api_get_attachments(&$body)
{ {
$text = $body; $text = $body;
@ -2623,13 +2727,16 @@ function api_get_attachments(&$body)
return $attachments; return $attachments;
} }
/**
*
* @param string $text
* @param string $bbcode
*
* @return array
* @todo Links at the first character of the post
*/
function api_get_entitities(&$text, $bbcode) function api_get_entitities(&$text, $bbcode)
{ {
/*
To-Do:
* Links at the first character of the post
*/
$a = get_app(); $a = get_app();
$include_entities = strtolower(x($_REQUEST, 'include_entities') ? $_REQUEST['include_entities'] : "false"); $include_entities = strtolower(x($_REQUEST, 'include_entities') ? $_REQUEST['include_entities'] : "false");
@ -2788,6 +2895,14 @@ function api_get_entitities(&$text, $bbcode)
return $entities; return $entities;
} }
/**
*
* @param array $item
* @param string $text
*
* @return string
*/
function api_format_items_embeded_images(&$item, $text) function api_format_items_embeded_images(&$item, $text)
{ {
$text = preg_replace_callback( $text = preg_replace_callback(
@ -2806,7 +2921,7 @@ function api_format_items_embeded_images(&$item, $text)
* *
* @param string $txt text * @param string $txt text
* @return array * @return array
* name => 'name' * 'name' => 'name',
* 'url => 'url' * 'url => 'url'
*/ */
function api_contactlink_to_array($txt) function api_contactlink_to_array($txt)
@ -2832,8 +2947,10 @@ function api_contactlink_to_array($txt)
* @brief return likes, dislikes and attend status for item * @brief return likes, dislikes and attend status for item
* *
* @param array $item array * @param array $item array
* @param string $type Return type (atom, rss, xml, json)
*
* @return array * @return array
* likes => int count * likes => int count,
* dislikes => int count * dislikes => int count
*/ */
function api_format_items_activities(&$item, $type = "json") function api_format_items_activities(&$item, $type = "json")
@ -2959,6 +3076,7 @@ function api_format_items_profiles(&$profile = null, $type = "json")
* @param array $r array of items * @param array $r array of items
* @param array $user_info * @param array $user_info
* @param bool $filter_user filter items by $user_info * @param bool $filter_user filter items by $user_info
* @param string $type Return type (atom, rss, xml, json)
*/ */
function api_format_items($r, $user_info, $filter_user = false, $type = "json") function api_format_items($r, $user_info, $filter_user = false, $type = "json")
{ {
@ -3073,6 +3191,13 @@ function api_format_items($r, $user_info, $filter_user = false, $type = "json")
return $ret; return $ret;
} }
/**
* Returns the remaining number of API requests available to the user before the API limit is reached.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_account_rate_limit_status($type) function api_account_rate_limit_status($type)
{ {
if ($type == "xml") { if ($type == "xml") {
@ -3101,6 +3226,13 @@ function api_account_rate_limit_status($type)
/// @TODO move to top of file or somwhere better /// @TODO move to top of file or somwhere better
api_register_func('api/account/rate_limit_status', 'api_account_rate_limit_status', true); api_register_func('api/account/rate_limit_status', 'api_account_rate_limit_status', true);
/**
* Returns the string "ok" in the requested format with a 200 OK HTTP status code.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_help_test($type) function api_help_test($type)
{ {
if ($type == 'xml') { if ($type == 'xml') {
@ -3115,6 +3247,12 @@ function api_help_test($type)
/// @TODO move to top of file or somwhere better /// @TODO move to top of file or somwhere better
api_register_func('api/help/test', 'api_help_test', false); api_register_func('api/help/test', 'api_help_test', false);
/**
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_lists($type) function api_lists($type)
{ {
$ret = array(); $ret = array();
@ -3125,6 +3263,14 @@ function api_lists($type)
/// @TODO move to top of file or somwhere better /// @TODO move to top of file or somwhere better
api_register_func('api/lists', 'api_lists', true); api_register_func('api/lists', 'api_lists', true);
/**
* Returns all lists the user subscribes to.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
* @see https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-list
*/
function api_lists_list($type) function api_lists_list($type)
{ {
$ret = array(); $ret = array();
@ -3136,11 +3282,11 @@ function api_lists_list($type)
api_register_func('api/lists/list', 'api_lists_list', true); api_register_func('api/lists/list', 'api_lists_list', true);
/** /**
* @brief Returns either the friends of the follower list * Considers friends and followers lists to be private and won't return
*
* Note: Considers friends and followers lists to be private and won't return
* anything if any user_id parameter is passed. * anything if any user_id parameter is passed.
* *
* @brief Returns either the friends of the follower list
*
* @param string $qtype Either "friends" or "followers" * @param string $qtype Either "friends" or "followers"
* @return boolean|array * @return boolean|array
* @throws ForbiddenException * @throws ForbiddenException
@ -3225,6 +3371,8 @@ function api_statuses_f($qtype)
/** /**
* Returns the user's friends.
*
* @brief Returns the list of friends of the provided user * @brief Returns the list of friends of the provided user
* *
* @deprecated By Twitter API in favor of friends/list * @deprecated By Twitter API in favor of friends/list
@ -3242,7 +3390,9 @@ function api_statuses_friends($type)
} }
/** /**
* @brief Returns the list of friends of the provided user * Returns the user's followers.
*
* @brief Returns the list of followers of the provided user
* *
* @deprecated By Twitter API in favor of friends/list * @deprecated By Twitter API in favor of friends/list
* *
@ -3310,6 +3460,13 @@ function api_friendships_incoming($type)
/// @TODO move to top of file or somewhere better /// @TODO move to top of file or somewhere better
api_register_func('api/friendships/incoming', 'api_friendships_incoming', true); api_register_func('api/friendships/incoming', 'api_friendships_incoming', true);
/**
* Returns the instance's configuration information.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_statusnet_config($type) function api_statusnet_config($type)
{ {
$a = get_app(); $a = get_app();
@ -3349,6 +3506,12 @@ function api_statusnet_config($type)
api_register_func('api/gnusocial/config', 'api_statusnet_config', false); api_register_func('api/gnusocial/config', 'api_statusnet_config', false);
api_register_func('api/statusnet/config', 'api_statusnet_config', false); api_register_func('api/statusnet/config', 'api_statusnet_config', false);
/**
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_statusnet_version($type) function api_statusnet_version($type)
{ {
// liar // liar
@ -3362,6 +3525,10 @@ api_register_func('api/gnusocial/version', 'api_statusnet_version', false);
api_register_func('api/statusnet/version', 'api_statusnet_version', false); api_register_func('api/statusnet/version', 'api_statusnet_version', false);
/** /**
*
* @param string $type Return type (atom, rss, xml, json)
* @param string $qtype
*
* @todo use api_format_data() to return data * @todo use api_format_data() to return data
*/ */
function api_ff_ids($type, $qtype) function api_ff_ids($type, $qtype)
@ -3399,11 +3566,27 @@ function api_ff_ids($type, $qtype)
return api_format_data("ids", $type, array('id' => $ids)); return api_format_data("ids", $type, array('id' => $ids));
} }
/**
* Returns the ID of every user the user is following.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
* @see https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-ids
*/
function api_friends_ids($type) function api_friends_ids($type)
{ {
return api_ff_ids($type, 'friends'); return api_ff_ids($type, 'friends');
} }
/**
* Returns the ID of every user following the user.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
* @see https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids
*/
function api_followers_ids($type) function api_followers_ids($type)
{ {
return api_ff_ids($type, 'followers'); return api_ff_ids($type, 'followers');
@ -3413,6 +3596,14 @@ function api_followers_ids($type)
api_register_func('api/friends/ids', 'api_friends_ids', true); api_register_func('api/friends/ids', 'api_friends_ids', true);
api_register_func('api/followers/ids', 'api_followers_ids', true); api_register_func('api/followers/ids', 'api_followers_ids', true);
/**
* Sends a new direct message.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
* @see https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-message
*/
function api_direct_messages_new($type) function api_direct_messages_new($type)
{ {
@ -3485,10 +3676,13 @@ function api_direct_messages_new($type)
api_register_func('api/direct_messages/new', 'api_direct_messages_new', true, API_METHOD_POST); api_register_func('api/direct_messages/new', 'api_direct_messages_new', true, API_METHOD_POST);
/** /**
* Destroys a direct message.
*
* @brief delete a direct_message from mail table through api * @brief delete a direct_message from mail table through api
* *
* @param string $type Known types are 'atom', 'rss', 'xml' and 'json' * @param string $type Known types are 'atom', 'rss', 'xml' and 'json'
* @return string * @return string
* @see https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/delete-message
*/ */
function api_direct_messages_destroy($type) function api_direct_messages_destroy($type)
{ {
@ -3562,6 +3756,14 @@ function api_direct_messages_destroy($type)
/// @TODO move to top of file or somewhere better /// @TODO move to top of file or somewhere better
api_register_func('api/direct_messages/destroy', 'api_direct_messages_destroy', true, API_METHOD_DELETE); api_register_func('api/direct_messages/destroy', 'api_direct_messages_destroy', true, API_METHOD_DELETE);
/**
*
* @param string $type Return type (atom, rss, xml, json)
* @param string $box
* @param string $verbose
*
* @return array|string
*/
function api_direct_messages_box($type, $box, $verbose) function api_direct_messages_box($type, $box, $verbose)
{ {
$a = get_app(); $a = get_app();
@ -3653,24 +3855,52 @@ function api_direct_messages_box($type, $box, $verbose)
return api_format_data("direct-messages", $type, $data); return api_format_data("direct-messages", $type, $data);
} }
/**
* Returns the most recent direct messages sent by the user.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
* @see https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-sent-message
*/
function api_direct_messages_sentbox($type) function api_direct_messages_sentbox($type)
{ {
$verbose = (x($_GET, 'friendica_verbose') ? strtolower($_GET['friendica_verbose']) : "false"); $verbose = (x($_GET, 'friendica_verbose') ? strtolower($_GET['friendica_verbose']) : "false");
return api_direct_messages_box($type, "sentbox", $verbose); return api_direct_messages_box($type, "sentbox", $verbose);
} }
/**
* Returns the most recent direct messages sent to the user.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
* @see https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-messages
*/
function api_direct_messages_inbox($type) function api_direct_messages_inbox($type)
{ {
$verbose = (x($_GET, 'friendica_verbose') ? strtolower($_GET['friendica_verbose']) : "false"); $verbose = (x($_GET, 'friendica_verbose') ? strtolower($_GET['friendica_verbose']) : "false");
return api_direct_messages_box($type, "inbox", $verbose); return api_direct_messages_box($type, "inbox", $verbose);
} }
/**
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_direct_messages_all($type) function api_direct_messages_all($type)
{ {
$verbose = (x($_GET, 'friendica_verbose') ? strtolower($_GET['friendica_verbose']) : "false"); $verbose = (x($_GET, 'friendica_verbose') ? strtolower($_GET['friendica_verbose']) : "false");
return api_direct_messages_box($type, "all", $verbose); return api_direct_messages_box($type, "all", $verbose);
} }
/**
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_direct_messages_conversation($type) function api_direct_messages_conversation($type)
{ {
$verbose = (x($_GET, 'friendica_verbose') ? strtolower($_GET['friendica_verbose']) : "false"); $verbose = (x($_GET, 'friendica_verbose') ? strtolower($_GET['friendica_verbose']) : "false");
@ -3683,6 +3913,12 @@ api_register_func('api/direct_messages/all', 'api_direct_messages_all', true);
api_register_func('api/direct_messages/sent', 'api_direct_messages_sentbox', true); api_register_func('api/direct_messages/sent', 'api_direct_messages_sentbox', true);
api_register_func('api/direct_messages', 'api_direct_messages_inbox', true); api_register_func('api/direct_messages', 'api_direct_messages_inbox', true);
/**
* Returns an OAuth Request Token.
*
* @param string $type Return type (atom, rss, xml, json)
* @see https://oauth.net/core/1.0/#auth_step1
*/
function api_oauth_request_token($type) function api_oauth_request_token($type)
{ {
$oauth1 = new FKOAuth1(); $oauth1 = new FKOAuth1();
@ -3696,6 +3932,14 @@ function api_oauth_request_token($type)
killme(); killme();
} }
/**
* Returns an OAuth Access Token.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
* @see https://oauth.net/core/1.0/#auth_step3
*/
function api_oauth_access_token($type) function api_oauth_access_token($type)
{ {
$oauth1 = new FKOAuth1(); $oauth1 = new FKOAuth1();
@ -4093,10 +4337,14 @@ function api_fr_photo_detail($type)
/** /**
* Updates the users profile image.
*
* @brief updates the profile image for the user (either a specified profile or the default profile) * @brief updates the profile image for the user (either a specified profile or the default profile)
* *
* @param string $type Known types are 'atom', 'rss', 'xml' and 'json' * @param string $type Known types are 'atom', 'rss', 'xml' and 'json'
*
* @return string * @return string
* @see https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_image
*/ */
function api_account_update_profile_image($type) function api_account_update_profile_image($type)
{ {
@ -4210,7 +4458,10 @@ api_register_func('api/friendica/photo/delete', 'api_fr_photo_delete', true, API
api_register_func('api/friendica/photo', 'api_fr_photo_detail', true); api_register_func('api/friendica/photo', 'api_fr_photo_detail', true);
api_register_func('api/account/update_profile_image', 'api_account_update_profile_image', true, API_METHOD_POST); api_register_func('api/account/update_profile_image', 'api_account_update_profile_image', true, API_METHOD_POST);
/**
*
* @param string $acl_string
*/
function check_acl_input($acl_string) function check_acl_input($acl_string)
{ {
if ($acl_string == null || $acl_string == " ") { if ($acl_string == null || $acl_string == " ") {
@ -4236,6 +4487,21 @@ function check_acl_input($acl_string)
return $contact_not_found; return $contact_not_found;
} }
/**
*
* @param string $mediatype
* @param array $media
* @param string $type
* @param string $album
* @param string $allow_cid
* @param string $deny_cid
* @param string $allow_gid
* @param string $deny_gid
* @param string $desc
* @param integer $profile
* @param boolean $visibility
* @param string $photo_id
*/
function save_media_to_database($mediatype, $media, $type, $album, $allow_cid, $deny_cid, $allow_gid, $deny_gid, $desc, $profile = 0, $visibility = false, $photo_id = null) function save_media_to_database($mediatype, $media, $type, $album, $allow_cid, $deny_cid, $allow_gid, $deny_gid, $desc, $profile = 0, $visibility = false, $photo_id = null)
{ {
$visitor = 0; $visitor = 0;
@ -4384,6 +4650,16 @@ function save_media_to_database($mediatype, $media, $type, $album, $allow_cid, $
} }
} }
/**
*
* @param string $hash
* @param string $allow_cid
* @param string $deny_cid
* @param string $allow_gid
* @param string $deny_gid
* @param string $filetype
* @param boolean $visibility
*/
function post_photo_item($hash, $allow_cid, $deny_cid, $allow_gid, $deny_gid, $filetype, $visibility = false) function post_photo_item($hash, $allow_cid, $deny_cid, $allow_gid, $deny_gid, $filetype, $visibility = false)
{ {
// get data about the api authenticated user // get data about the api authenticated user
@ -4429,6 +4705,14 @@ function post_photo_item($hash, $allow_cid, $deny_cid, $allow_gid, $deny_gid, $f
item_store($arr); item_store($arr);
} }
/**
*
* @param string $type
* @param int $scale
* @param string $photo_id
*
* @return array
*/
function prepare_photo_data($type, $scale, $photo_id) function prepare_photo_data($type, $scale, $photo_id)
{ {
$scale_sql = ($scale === false ? "" : sprintf("AND scale=%d", intval($scale))); $scale_sql = ($scale === false ? "" : sprintf("AND scale=%d", intval($scale)));
@ -4702,13 +4986,16 @@ function api_share_as_retweet(&$item)
return $reshared_item; return $reshared_item;
} }
/**
*
* @param string $profile
*
* @return string|false
* @todo remove trailing junk from profile url
* @todo pump.io check has to check the website
*/
function api_get_nick($profile) function api_get_nick($profile)
{ {
/* To-Do:
- remove trailing junk from profile url
- pump.io check has to check the website
*/
$nick = ""; $nick = "";
$r = q( $r = q(
@ -4783,6 +5070,12 @@ function api_get_nick($profile)
return false; return false;
} }
/**
*
* @param array $item
*
* @return array
*/
function api_in_reply_to($item) function api_in_reply_to($item)
{ {
$in_reply_to = array(); $in_reply_to = array();
@ -4841,6 +5134,12 @@ function api_in_reply_to($item)
return $in_reply_to; return $in_reply_to;
} }
/**
*
* @param string $Text
*
* @return string
*/
function api_clean_plain_items($Text) function api_clean_plain_items($Text)
{ {
$include_entities = strtolower(x($_REQUEST, 'include_entities') ? $_REQUEST['include_entities'] : "false"); $include_entities = strtolower(x($_REQUEST, 'include_entities') ? $_REQUEST['include_entities'] : "false");
@ -4890,6 +5189,12 @@ function api_clean_attachments($body)
return $body; return $body;
} }
/**
*
* @param array $contacts
*
* @return array
*/
function api_best_nickname(&$contacts) function api_best_nickname(&$contacts)
{ {
$best_contact = array(); $best_contact = array();
@ -4952,7 +5257,13 @@ function api_best_nickname(&$contacts)
} }
} }
// return all or a specified group of the user with the containing contacts /**
* Return all or a specified group of the user with the containing contacts.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_friendica_group_show($type) function api_friendica_group_show($type)
{ {
$a = get_app(); $a = get_app();
@ -5010,7 +5321,13 @@ function api_friendica_group_show($type)
api_register_func('api/friendica/group_show', 'api_friendica_group_show', true); api_register_func('api/friendica/group_show', 'api_friendica_group_show', true);
// delete the specified group of the user /**
* Delete the specified group of the user.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_friendica_group_delete($type) function api_friendica_group_delete($type)
{ {
$a = get_app(); $a = get_app();
@ -5066,7 +5383,13 @@ function api_friendica_group_delete($type)
api_register_func('api/friendica/group_delete', 'api_friendica_group_delete', true, API_METHOD_DELETE); api_register_func('api/friendica/group_delete', 'api_friendica_group_delete', true, API_METHOD_DELETE);
// create the specified group with the posted array of contacts /**
* Create the specified group with the posted array of contacts.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_friendica_group_create($type) function api_friendica_group_create($type)
{ {
$a = get_app(); $a = get_app();
@ -5144,7 +5467,13 @@ function api_friendica_group_create($type)
api_register_func('api/friendica/group_create', 'api_friendica_group_create', true, API_METHOD_POST); api_register_func('api/friendica/group_create', 'api_friendica_group_create', true, API_METHOD_POST);
// update the specified group with the posted array of contacts /**
* Update the specified group with the posted array of contacts.
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_friendica_group_update($type) function api_friendica_group_update($type)
{ {
$a = get_app(); $a = get_app();
@ -5211,6 +5540,12 @@ function api_friendica_group_update($type)
api_register_func('api/friendica/group_update', 'api_friendica_group_update', true, API_METHOD_POST); api_register_func('api/friendica/group_update', 'api_friendica_group_update', true, API_METHOD_POST);
/**
*
* @param string $type Return type (atom, rss, xml, json)
*
* @return array|string
*/
function api_friendica_activity($type) function api_friendica_activity($type)
{ {
$a = get_app(); $a = get_app();
@ -5282,10 +5617,10 @@ function api_friendica_notification($type)
} }
/** /**
* @brief Set notification as seen and returns associated item (if possible)
*
* POST request with 'id' param as notification id * POST request with 'id' param as notification id
* *
* @brief Set notification as seen and returns associated item (if possible)
*
* @param string $type Known types are 'atom', 'rss', 'xml' and 'json' * @param string $type Known types are 'atom', 'rss', 'xml' and 'json'
* @return string * @return string
*/ */
@ -5393,7 +5728,7 @@ api_register_func('api/friendica/direct_messages_setseen', 'api_friendica_direct
* @brief search for direct_messages containing a searchstring through api * @brief search for direct_messages containing a searchstring through api
* *
* @param string $type Known types are 'atom', 'rss', 'xml' and 'json' * @param string $type Known types are 'atom', 'rss', 'xml' and 'json'
* @return string (success: success=true if found and search_result contains found messages * @return string (success: success=true if found and search_result contains found messages,
* success=false if nothing was found, search_result='nothing found', * success=false if nothing was found, search_result='nothing found',
* error: result=error with error message) * error: result=error with error message)
*/ */