From 17e0ab99e61ddee0bdeabd60c35fbbde0ba387fe Mon Sep 17 00:00:00 2001 From: Arkshine Date: Fri, 1 Aug 2014 00:58:02 +0200 Subject: [PATCH] Geoip: Update documentation. --- plugins/include/geoip.inc | 172 ++++++++++++++++++++------------------ 1 file changed, 91 insertions(+), 81 deletions(-) diff --git a/plugins/include/geoip.inc b/plugins/include/geoip.inc index 02c95760..7739f0dc 100755 --- a/plugins/include/geoip.inc +++ b/plugins/include/geoip.inc @@ -12,77 +12,87 @@ // #if defined geoip_included - #endinput + #endinput #endif #define _geoip_included #if AMXX_VERSION_NUM >= 175 - #pragma reqlib geoip - #if !defined AMXMODX_NOAUTOLOAD - #pragma loadlib geoip - #endif + #pragma reqlib geoip + #if !defined AMXMODX_NOAUTOLOAD + #pragma loadlib geoip + #endif #else - #pragma library geoip + #pragma library geoip #endif -/// IP addresses passed to these natives can contain ports, the ports will be ignored. +/** + * @global IP addresses passed to these natives can contain ports, the ports will be ignored. + */ /** - * Lookup the two character country code for a given IP address. + * Look up the two character country code for a given IP address. * e.g: "US", "CA", etc. * - * @param ip The IP address to lookup. - * @param result The result buffer. If the lookup does not succeed, the buffer is not modified. - * @return true on a successful lookup, false on a failed lookup. + * @param ip The IP address to lookup. + * @param result The result buffer. If the lookup does not succeed, the buffer is not modified. + * + * @return true on a successful lookup, false on a failed lookup. */ native bool:geoip_code2_ex(const ip[], result[3]); /** - * Lookup the three character country code for a given IP address. + * Look up the three character country code for a given IP address. * e.g: "USA", "cAN", etc. * - * @param ip The IP address to lookup. - * @param result The result buffer. If the lookup does not succeed, the buffer is not modified. - * @return true on a successful lookup, false on a failed lookup. + * @param ip The IP address to lookup. + * @param result The result buffer. If the lookup does not succeed, the buffer is not modified. + * + * @return true on a successful lookup, false on a failed lookup. */ native bool:geoip_code3_ex(const ip[], result[4]); /** - * @deprecated * Lookup the two character country code for a given IP address. * - * @note This native will overflow the buffer by one cell on an unknown ip lookup! - * @note Use geoip_code2_ex instead! + * @deprecated This native will overflow the buffer by one cell on an unknown ip lookup! + * Use geoip_code2_ex instead. * - * @param ip The IP address to lookup. - * @param result The result buffer. + * @param ip The IP address to lookup. + * @param result The result buffer. + * + * @return 1 on a successful lookup, 0 otherwise. */ +//#pragma deprecated Use geoip_code2_ex() instead. native geoip_code2(const ip[], ccode[3]); /** - * @deprecated * Lookup the three character country code for a given IP address. * - * @note This native will overflow the buffer by one cell on an unknown ip lookup! - * @note Use geoip_code3_ex instead! + * @deprecated This native will overflow the buffer by one cell on an unknown ip lookup! + * Use geoip_code3_ex instead. * - * @param ip The IP address to lookup. - * @param result The result buffer. + * @param ip The IP address to lookup. + * @param result The result buffer. + * + * @return 1 on a successful lookup, 0 otherwise. */ +//#pragma deprecated Use geoip_code3() instead. native geoip_code3(const ip[], result[4]); /** * Lookup the full country name for the given IP address. Sets the buffer to "error" on * an unsuccessful lookup. * - * @param ip The IP address to lookup. - * @param result The result of the geoip lookup. - * @param len The maximum length of the result buffer. - * @param id An optional player's index in order to return the result + * @param ip The IP address to lookup. + * @param result The result of the geoip lookup. + * @param len The maximum length of the result buffer. + * @param id An optional player's index in order to return the result * in the player's language, if supported. * -1: the default language, which is english. * 0: the server language. You can use LANG_SERVER define. - * >=1: the player's language. + * >=1: the player's language. + * + * @return The result length on successful lookup, 0 otherwise. */ native geoip_country(const ip[], result[], len, id = -1); @@ -93,47 +103,47 @@ native geoip_country(const ip[], result[], len, id = -1); * http://dev.maxmind.com/geoip/geoip2/geolite2/ (MaxMind DB binary) */ -/** +/** * Look up the full city name for the given IP address. - * - * @param ip The IP address to look up. - * @param result The result of the geoip look up. - * @param len The maximum length of the result buffer. - * @param id An optional player's index in order to return the result + * + * @param ip The IP address to look up. + * @param result The result of the geoip look up. + * @param len The maximum length of the result buffer. + * @param id An optional player's index in order to return the result * in the player's language, if supported. * -1: the default language, which is english. * 0: the server language. You can use LANG_SERVER define. - * >=1: the player's language. + * >=1: the player's language. * * @return The result length on successful lookup, 0 otherwise. - */ -native geoip_city(const ip[], result[], len, id = -1); + */ +native geoip_city(const ip[], result[], len, id = -1); /** * Look up the region/state code for the given IP address. * e.g. "US-OH", "DE-HH", IT-82, "FR-U", etc. * - * @param ip The IP address to look up. - * @param result The result of the geoip look up. - * @param len The maximum length of the result buffer. + * @param ip The IP address to look up. + * @param result The result of the geoip look up. + * @param len The maximum length of the result buffer. * - * @return The result length on successful lookup, 0 otherwise. + * @return The result length on successful lookup, 0 otherwise. */ native geoip_region_code(const ip[], result[], len); /** * Look up the full region/state name for the given IP address. * - * @param ip The IP address to look up. - * @param result The result of the geoip look up. - * @param len The maximum length of the result buffer. - * @param id An optional player's index in order to return the result + * @param ip The IP address to look up. + * @param result The result of the geoip look up. + * @param len The maximum length of the result buffer. + * @param id An optional player's index in order to return the result * in the player's language, if supported. * -1: the default language, which is english. * 0: the server language. You can use LANG_SERVER define. - * >=1: the player's language. + * >=1: the player's language. * - * @return The result length on successful lookup, 0 otherwise. + * @return The result length on successful lookup, 0 otherwise. */ native geoip_region_name(const ip[], result[], len, id = -1); @@ -141,42 +151,42 @@ native geoip_region_name(const ip[], result[], len, id = -1); * Look up the full time zone for the given IP address. * e.g. America/Los_Angeles, Europe/Paris. * - * @param ip The IP address to look up. - * @param result The result of the geoip look up. - * @param len The maximum length of the result buffer. + * @param ip The IP address to look up. + * @param result The result of the geoip look up. + * @param len The maximum length of the result buffer. * - * @return The result length on successful lookup, 0 otherwise. + * @return The result length on successful lookup, 0 otherwise. */ native geoip_timezone(const ip[], result[], len); -/** +/** * Look up the city's latitude for the given IP address. - * - * @param ip The IP address to look up. * - * @return The result of the geoip look up, 0 if latitude is not found. - */ -native Float:geoip_latitude(const ip[]); + * @param ip The IP address to look up. + * + * @return The result of the geoip look up, 0 if latitude is not found. + */ +native Float:geoip_latitude(const ip[]); -/** - * Look up the city's longitude for the given IP address. - * - * @param ip The IP address to look up. +/** + * Look up the city's longitude for the given IP address. * - * @return The result of the geoip look up, 0 if longitude is not found. - */ + * @param ip The IP address to look up. + * + * @return The result of the geoip look up, 0 if longitude is not found. + */ native Float:geoip_longitude(const ip[]); /** * Calculate the distance between geographical coordinates, latitude and longitude. * - * @param lat1 The first IP latitude. - * @param lon1 The first IP longitude. - * @param lat2 The second IP latitude. - * @param lon2 The second IP longitude. - * @param system The system of measurement, 0 = Metric(kilometers) or 1 = English(miles). + * @param lat1 The first IP latitude. + * @param lon1 The first IP longitude. + * @param lat2 The second IP latitude. + * @param lon2 The second IP longitude. + * @param system The system of measurement, 0 = Metric(kilometers) or 1 = English(miles). * - * @return The distance as result in specified system of measurement. + * @return The distance as result in specified system of measurement. */ #define SYSTEM_METRIC 0 // kilometers #define SYSTEM_IMPERIAL 1 // statute miles @@ -187,13 +197,13 @@ native Float:geoip_distance(Float:lat1, Float:lon1, Float:lat2, Float:lon2, syst * Look up the continent code for a given IP address. * * @note The code can be retrieved as integer (See CONTINENT_* constants.) or string (2 characters). - * @note Possible continent codes are AF, AS, EU, NA, OC, SA for + * @note Possible continent codes are AF, AS, EU, NA, OC, SA for * Africa(1), Asia(2), Europe(3), North America(4), Oceania(5) and South America(6). * - * @param ip The IP address to look up. - * @param result The result of the geoip look up. + * @param ip The IP address to look up. + * @param result The result of the geoip look up. * - * @return The continent id on successful lookup, 0 otherwise. + * @return The continent id on successful lookup, 0 otherwise. */ enum Continent { @@ -210,15 +220,15 @@ native Continent:geoip_continent_code(const ip[], result[3]); /** * Look up the full continent name for the given IP address. * - * @param ip The IP address to look up. - * @param result The result of the geoip look up. - * @param len The maximum length of the result buffer. - * @param id An optional player's index in order to return the result + * @param ip The IP address to look up. + * @param result The result of the geoip look up. + * @param len The maximum length of the result buffer. + * @param id An optional player's index in order to return the result * in the player's language, if supported. * -1: the default language, which is english. * 0: the server language. You can use LANG_SERVER define. - * >=1: the player's language. + * >=1: the player's language. * - * @return The result length on successful lookup, 0 otherwise. + * @return The result length on successful lookup, 0 otherwise. */ native geoip_continent_name(const ip[], result[], len, id = -1);