From 1a737be2b408135177a9e94dcffd0f68c0aca90b Mon Sep 17 00:00:00 2001 From: Klaus Weidenbach Date: Tue, 5 Sep 2017 00:23:42 +0200 Subject: :bulb: Improving Doxygen documentation. Fix some Doxygen parsing errors. Improve hooks documentation. --- include/network.php | 214 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 141 insertions(+), 73 deletions(-) (limited to 'include/network.php') diff --git a/include/network.php b/include/network.php index 2caf29ab5..3569874be 100644 --- a/include/network.php +++ b/include/network.php @@ -1,6 +1,7 @@ content * * \e string \b debug => from curl_info() */ -function z_post_url($url,$params, $redirects = 0, $opts = array()) { +function z_post_url($url, $params, $redirects = 0, $opts = array()) { // logger('url: ' . $url); // logger('params: ' . print_r($params,true)); @@ -276,13 +277,10 @@ function z_post_url($url,$params, $redirects = 0, $opts = array()) { @curl_setopt($ch, CURLOPT_USERPWD, $opts['http_auth']); } - if(x($opts,'cookiejar')) @curl_setopt($ch, CURLOPT_COOKIEJAR, $opts['cookiejar']); if(x($opts,'cookiefile')) @curl_setopt($ch, CURLOPT_COOKIEFILE, $opts['cookiefile']); - - if(x($opts,'cookie')) @curl_setopt($ch, CURLOPT_COOKIE, $opts['cookie']); @@ -423,7 +421,7 @@ function http_status($val, $msg = '') { * integer HTTP status result value * @param string $msg * optional message - * @return does not return, process is terminated + * @return void does not return, process is terminated */ function http_status_exit($val, $msg = '') { http_status($val, $msg); @@ -431,10 +429,10 @@ function http_status_exit($val, $msg = '') { } /** - * @brief convert an XML document to a normalised, case-corrected array used by webfinger. + * @brief Convert an XML document to a normalised, case-corrected array used by webfinger. * * @param string|array|SimpleXMLElement $xml_element - * @param int $recursion_depth[in,out] + * @param[in,out] int $recursion_depth * @return NULL|string|array */ function convert_xml_element_to_array($xml_element, &$recursion_depth=0) { @@ -501,14 +499,14 @@ function z_dns_check($h,$check_mx = 0) { } /** - * @brief Validates a given URL + * @brief Validates a given URL. * * Take a URL from the wild, prepend http:// if necessary and check DNS to see * if it's real (or check if is a valid IP address). * * @see z_dns_check() * - * @param string $url[in,out] URL to check + * @param[in,out] string $url URL to check * @return boolean Return true if it's OK, false if something is wrong with it */ function validate_url(&$url) { @@ -593,6 +591,7 @@ function allowed_url($url) { } } } + return $found; } @@ -658,7 +657,7 @@ function allowed_email($email) { -function parse_xml_string($s,$strict = true) { +function parse_xml_string($s, $strict = true) { if($strict) { if(! strstr($s,' $webbie, 'protocol' => $protocol, 'success' => false, 'webfinger' => $x); + $arr = [ + 'address' => $webbie, + 'protocol' => $protocol, + 'success' => false, + 'webfinger' => $x + ]; + /** + * @hooks discover_channel_webfinger + * Called when performing a webfinger lookup. + * * \e string \b address - The webbie + * * \e string \b protocol + * * \e array \b webfinger - The result from webfinger_rfc7033() + * * \e boolean \b success - The return value, default false + */ call_hooks('discover_channel_webfinger', $arr); if($arr['success']) return true; return false; - } -function webfinger_rfc7033($webbie,$zot = false) { +/** + * @brief Fetch and return a webfinger for a webbie. + * + * @param string $webbie - The webbie + * @param boolean $zot (optional) default false + * @return boolean|string false or associative array from result JSON + */ +function webfinger_rfc7033($webbie, $zot = false) { if(strpos($webbie,'@')) { $lhs = substr($webbie,0,strpos($webbie,'@')); @@ -1199,6 +1230,7 @@ function webfinger_rfc7033($webbie,$zot = false) { if($m) { if($m['scheme'] !== 'https') return false; + $rhs = $m['host'] . (($m['port']) ? ':' . $m['port'] : ''); $resource = urlencode($webbie); } @@ -1211,20 +1243,19 @@ function webfinger_rfc7033($webbie,$zot = false) { // and results in a 406 (Not Acceptable) response, and will also incorrectly produce an XML // document if you use 'application/jrd+json, */*'. We could set this to application/jrd+json, // but some test webfinger servers may not explicitly set the content type and they would be - // blocked. The best compromise until Mastodon is fixed is to remove the Accept header which is - // accomplished by setting it to nothing. + // blocked. The best compromise until Mastodon is fixed is to remove the Accept header which is + // accomplished by setting it to nothing. $counter = 0; - $s = z_fetch_url('https://' . $rhs . '/.well-known/webfinger?f=&resource=' . $resource . (($zot) ? '&zot=1' : ''), + $s = z_fetch_url('https://' . $rhs . '/.well-known/webfinger?f=&resource=' . $resource . (($zot) ? '&zot=1' : ''), false, $counter, [ 'headers' => [ 'Accept:' ] ]); if($s['success']) { - $j = json_decode($s['body'],true); + $j = json_decode($s['body'], true); return($j); } return false; - } function old_webfinger($webbie) { @@ -1604,7 +1635,13 @@ function check_siteallowed($url) { $retvalue = true; $arr = array('url' => $url); - call_hooks('check_siteallowed',$arr); + /** + * @hooks check_siteallowed + * Used to over-ride or bypass the site black/white block lists. + * * \e string \b url + * * \e boolean \b allowed - optional return value set in hook + */ + call_hooks('check_siteallowed', $arr); if(array_key_exists('allowed',$arr)) return $arr['allowed']; @@ -1643,7 +1680,13 @@ function check_channelallowed($hash) { $retvalue = true; $arr = array('hash' => $hash); - call_hooks('check_channelallowed',$arr); + /** + * @hooks check_channelallowed + * Used to over-ride or bypass the channel black/white block lists. + * * \e string \b hash + * * \e boolean \b allowed - optional return value set in hook + */ + call_hooks('check_channelallowed', $arr); if(array_key_exists('allowed',$arr)) return $arr['allowed']; @@ -1732,6 +1775,10 @@ function network_to_name($s) { NETWORK_MYSPACE => t('MySpace'), ); + /** + * @hooks network_to_name + * @deprecated + */ call_hooks('network_to_name', $nets); $search = array_keys($nets); @@ -1743,7 +1790,7 @@ function network_to_name($s) { /** * @brief Send a text email message. * - * @param array $params an assoziative array with: + * @param array $params an associative array with: * * \e string \b fromName name of the sender * * \e string \b fromEmail email of the sender * * \e string \b replyTo replyTo address to direct responses @@ -1774,6 +1821,10 @@ function z_mail($params) { $params['sent'] = false; $params['result'] = false; + /** + * @hooks email_send + * * \e params @see z_mail() + */ call_hooks('email_send', $params); if($params['sent']) { @@ -1921,60 +1972,78 @@ function service_plink($contact, $guid) { $plink = $url . '/channel/' . $handle . '?f=&mid=' . $guid; $x = [ 'xchan' => $contact, 'guid' => $guid, 'url' => $url, 'plink' => $plink ]; + /** + * @hooks service_plink + * * \e array \b xchan + * * \e string \b guid + * * \e string \b url + * * \e string \b plink will get returned + */ call_hooks('service_plink', $x); return $x['plink']; } + +/** + * @brief + * + * @param array $mimeTypes + * @param string $acceptedTypes by default false will use $_SERVER['HTTP_ACCEPT'] + * @return array|NULL + */ function getBestSupportedMimeType($mimeTypes = null, $acceptedTypes = false) { - // Values will be stored in this array + // Values will be stored in this array + $AcceptTypes = []; if($acceptedTypes === false) $acceptedTypes = $_SERVER['HTTP_ACCEPT']; - $AcceptTypes = Array (); - - // Accept header is case insensitive, and whitespace isn’t important - $accept = strtolower(str_replace(' ', '', $acceptedTypes)); - // divide it into parts in the place of a "," - $accept = explode(',', $accept); - foreach ($accept as $a) { - // the default quality is 1. - $q = 1; - // check if there is a different quality - if (strpos($a, ';q=')) { - // divide "mime/type;q=X" into two parts: "mime/type" i "X" - list($a, $q) = explode(';q=', $a); - } - // mime-type $a is accepted with the quality $q - // WARNING: $q == 0 means, that mime-type isn’t supported! - $AcceptTypes[$a] = $q; - } - arsort($AcceptTypes); - - // if no parameter was passed, just return parsed data - if (!$mimeTypes) return $AcceptTypes; - - $mimeTypes = array_map('strtolower', (array)$mimeTypes); - - // let’s check our supported types: - foreach ($AcceptTypes as $mime => $q) { - if ($q && in_array($mime, $mimeTypes)) return $mime; - } - // no mime-type found - return null; -} + // Accept header is case insensitive, and whitespace isn’t important + $accept = strtolower(str_replace(' ', '', $acceptedTypes)); + // divide it into parts in the place of a "," + $accept = explode(',', $accept); + foreach ($accept as $a) { + // the default quality is 1. + $q = 1; + // check if there is a different quality + if (strpos($a, ';q=')) { + // divide "mime/type;q=X" into two parts: "mime/type" i "X" + list($a, $q) = explode(';q=', $a); + } + // mime-type $a is accepted with the quality $q + // WARNING: $q == 0 means, that mime-type isn’t supported! + $AcceptTypes[$a] = $q; + } + arsort($AcceptTypes); + // if no parameter was passed, just return parsed data + if (!$mimeTypes) return $AcceptTypes; -function jsonld_document_loader($url) { + $mimeTypes = array_map('strtolower', (array)$mimeTypes); - // perform caching for jsonld normaliser + // let’s check our supported types: + foreach ($AcceptTypes as $mime => $q) { + if ($q && in_array($mime, $mimeTypes)) return $mime; + } + + // no mime-type found + return null; +} + +/** + * @brief Perform caching for jsonld normaliser. + * + * @param string $url + * @return mixed|boolean|array + */ +function jsonld_document_loader($url) { require_once('library/jsonld/jsonld.php'); $cachepath = 'store/[data]/ldcache'; if(! is_dir($cachepath)) - os_mkdir($cachepath,STORAGE_DEFAULT_PERMISSIONS,true); + os_mkdir($cachepath, STORAGE_DEFAULT_PERMISSIONS, true); $filename = $cachepath . '/' . urlencode($url); if(file_exists($filename) && filemtime($filename) > time() - (12 * 60 * 60)) { @@ -1983,7 +2052,7 @@ function jsonld_document_loader($url) { $r = jsonld_default_document_loader($url); if($r) { - file_put_contents($filename,json_encode($r)); + file_put_contents($filename, json_encode($r)); return $r; } @@ -1993,5 +2062,4 @@ function jsonld_document_loader($url) { } return []; - } \ No newline at end of file -- cgit v1.2.3