Consistency overhaul

README.md

@@ -7,6 +7,122 @@ The current latest version is **0.3.7-R2-2-1**.
 
 The master branch HEAD does not currently contain any RC libaries.
 
+## Tags
+
+The latest version of the SA:MP includes introduce many more tags to functions and callbacks.  These
+are useful in the long run, but slightly annoying to upgrade to.  There are three symbols:
+`NO_TAGS`, `WEAK_TAGS`, and `STRONG_TAGS`; that you can define before including `<a_samp>`, each one
+enabling progressively more checks:
+
+```pawn
+#define STRONG_TAGS
+#include <a_samp>
+```
+
+To encourage some adoption, the default is `WEAK_TAGS`.  Most old code uses will simply give a
+warning when the wrong tag is found:
+
+```pawn
+// Gives a warning:
+SetPlayerControllable(playerid, 1);
+
+// Should be:
+SetPlayerControllable(playerid, true);
+```
+
+However, there's a problem - callbacks give an error:
+
+```pawn
+forward OnPlayerStateChange(playerid, PLAYER_STATE:newstate, PLAYER_STATE:oldstate);
+
+public OnPlayerStateChange(playerid, newstate, oldstate)
+{
+}
+```
+
+This gives an error, when it should be fine.  Fixing it in a mode is easy - just use the correct
+tags on the variables in the callbacks.  Fixing it in a generic library needs a few extra lines to
+define a default tag when one isn't found (i.e. the user isn't using the improved includes):
+
+```pawn
+#if !defined PLAYER_STATE
+	// Use the default tag (none, `_:`) when the improved includes aren't found.
+	#define PLAYER_STATE: _:
+#endif
+public OnPlayerStateChange(playerid, PLAYER_STATE:newstate, PLAYER_STATE:oldstate)
+{
+	return Hooked_OnPlayerStateChange(playerid, newstate, oldstate);
+}
+
+// Don't forget to use ALS as normal.
+forward Hooked_OnPlayerStateChange(playerid, PLAYER_STATE:newstate, PLAYER_STATE:oldstate);
+```
+
+### Complete List
+
+* `OnPlayerStateChange`
+
+```pawn
+#if !defined PLAYER_STATE
+	#define PLAYER_STATE: _:
+#endif
+forward OnPlayerStateChange(playerid, PLAYER_STATE:newstate, PLAYER_STATE:oldstate);
+```
+
+* `OnPlayerClickPlayer`
+
+```pawn
+#if !defined CLICK_SOURCE
+	#define CLICK_SOURCE: _:
+#endif
+forward OnPlayerClickPlayer(playerid, clickedplayerid, CLICK_SOURCE:source);
+```
+
+* `OnPlayerEditObject`
+
+```pawn
+#if !defined EDIT_RESPONSE
+	#define EDIT_RESPONSE: _:
+#endif
+forward OnPlayerEditObject(playerid, playerobject, objectid, EDIT_RESPONSE:response, Float:fX, Float:fY, Float:fZ, Float:fRotX, Float:fRotY, Float:fRotZ);
+```
+
+* `OnPlayerEditAttachedObject`
+
+```pawn
+#if !defined EDIT_RESPONSE
+	#define EDIT_RESPONSE: _:
+#endif
+forward OnPlayerEditAttachedObject(playerid, EDIT_RESPONSE:response, index, modelid, boneid, Float:fOffsetX, Float:fOffsetY, Float:fOffsetZ, Float:fRotX, Float:fRotY, Float:fRotZ, Float:fScaleX, Float:fScaleY, Float:fScaleZ);
+```
+
+* `OnPlayerSelectObject`
+
+```pawn
+#if !defined SELECT_OBJECT
+	#define SELECT_OBJECT: _:
+#endif
+forward OnPlayerSelectObject(playerid, SELECT_OBJECT:type, objectid, modelid, Float:fX, Float:fY, Float:fZ);
+```
+
+* `OnPlayerWeaponShot`
+
+```pawn
+#if !defined BULLET_HIT_TYPE
+	#define BULLET_HIT_TYPE: _:
+#endif
+forward OnPlayerWeaponShot(playerid, weaponid, BULLET_HIT_TYPE:hittype, hitid, Float:fX, Float:fY, Float:fZ);
+```
+
+* `OnPlayerKeyStateChange`
+
+```pawn
+#if !defined KEY
+	#define KEY: _:
+#endif
+forward OnPlayerKeyStateChange(playerid, KEY:newkeys, KEY:oldkeys);
+```
+
 ## Why?
 
 The package management system built into the `sampctl` tool is based on GitHub

a_http.inc

@@ -18,38 +18,46 @@
 // --------------------------------------------------
 
 // HTTP requests
-#define HTTP_GET                               (1)
-#define HTTP_POST                              (2)
-#define HTTP_HEAD                              (3)
+#define HTTP_METHOD: __TAG(HTTP_METHOD):
+enum HTTP_METHOD:
+{
+	HTTP_GET                                   = 1,
+	HTTP_POST,
+	HTTP_HEAD
+}
 
 // HTTP error response codes
-// These codes compliment ordinary HTTP response codes returned in 'response_code'
-// (10x) (20x OK) (30x Moved) (40x Unauthorised) (50x Server Error)  
-#define HTTP_ERROR_BAD_HOST                    (1)
-#define HTTP_ERROR_NO_SOCKET                   (2)
-#define HTTP_ERROR_CANT_CONNECT                (3)
-#define HTTP_ERROR_CANT_WRITE                  (4)
-#define HTTP_ERROR_CONTENT_TOO_BIG             (5)
-#define HTTP_ERROR_MALFORMED_RESPONSE          (6)
+// These codes compliment ordinary HTTP response codes returned in 'responseCode'
+// (10x) (20x OK) (30x Moved) (40x Unauthorised) (50x Server Error)
+#define HTTP_ERROR: __TAG(HTTP_ERROR):
+enum HTTP_ERROR:
+{
+	HTTP_ERROR_BAD_HOST                        = 1,
+	HTTP_ERROR_NO_SOCKET,
+	HTTP_ERROR_CANT_CONNECT,
+	HTTP_ERROR_CANT_WRITE,
+	HTTP_ERROR_CONTENT_TOO_BIG,
+	HTTP_ERROR_MALFORMED_RESPONSE
+}
 
 /// <summary>Sends a threaded HTTP request.</summary>
 /// <param name="index">ID used to differentiate requests that are sent to the same callback (useful for playerids)</param>
-/// <param name="type">The type of request you wish to send</param>
+/// <param name="method">The type of request you wish to send</param>
 /// <param name="url">The URL you want to request. (Without 'http://')</param>
 /// <param name="data">Any POST data you want to send with the request</param>
 /// <param name="callback">Name of the callback function you want to use to handle responses to this request</param>
 /// <remarks>This function was added in <b>SA-MP 0.3b</b> and will not work in earlier versions!</remarks>
 /// <returns><b><c>1</c></b> on success, <b><c>0</c></b> on failure.</returns>
 /// <remarks>
-///   <b>Request types:</b><p/>
+///   <b>Request types:</b><br />
 ///   <ul>
 ///     <li><b><c>HTTP_GET</c></b></li>
 ///     <li><b><c>HTTP_POST</c></b></li>
 ///     <li><b><c>HTTP_HEAD</c></b></li>
 ///   </ul>
 /// </remarks>
 /// <remarks>
-///   <b>Response codes:</b><p/>
+///   <b>Response codes:</b><br />
 ///   <ul>
 ///     <li><b><c>HTTP_ERROR_BAD_HOST</c></b></li>
 ///     <li><b><c>HTTP_ERROR_NO_SOCKET</c></b></li>
@@ -60,7 +68,7 @@
 ///     <li>+ standard HTTP response codes</li>
 ///   </ul>
 /// </remarks>
-native HTTP(index, type, const url[], const data[], const callback[]);
+native HTTP(index, HTTP_METHOD:method, const url[], const data[], const callback[]);
 
-// example HTTP callback: public MyHttpResponse(index, response_code, const data[]) { ... }
+// example HTTP callback: public MyHttpResponse(index, responseCode, const data[]) { ... }