android: Added SDL_AndroidRequestPermissionAsync.

include/SDL3/SDL_system.h

@@ -402,7 +402,18 @@ extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
 /**
  * Request permissions at runtime.
  *
+ * You do not need to call this for built-in functionality of SDL; recording
+ * from a microphone or reading images from a camera, using standard SDL
+ * APIs, will manage permission requests for you.
+ *
  * This blocks the calling thread until the permission is granted or denied.
+ * if the app already has the requested permission, this returns immediately,
+ * but may block indefinitely until the user responds to the system's
+ * permission request dialog.
+ *
+ * If possible, you should _not_ use this function. You should use
+ * SDL_AndroidRequestPermissionAsync and deal with the response in a callback
+ * at a later time, and possibly in a different thread.
  *
  * \param permission The permission to request.
  * \returns SDL_TRUE if the permission was granted, SDL_FALSE otherwise.
@@ -411,6 +422,39 @@ extern DECLSPEC const char * SDLCALL SDL_AndroidGetExternalStoragePath(void);
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permission);
 
+
+typedef void (SDLCALL *SDL_AndroidRequestPermissionCallback)(void *userdata, const char *permission, SDL_bool granted);
+
+/**
+ * Request permissions at runtime, asynchronously.
+ *
+ * You do not need to call this for built-in functionality of SDL; recording
+ * from a microphone or reading images from a camera, using standard SDL
+ * APIs, will manage permission requests for you.
+ *
+ * This function never blocks. Instead, the app-supplied callback will be
+ * called when a decision has been made. This callback may happen on a
+ * different thread, and possibly much later, as it might wait on a user to
+ * respond to a system dialog. If permission has already been granted for
+ * a specific entitlement, the callback will still fire, probably on the
+ * current thread and before this function returns.
+ *
+ * If the request submission fails, this function returns -1 and the
+ * callback will NOT be called, but this should only happen in
+ * catastrophic conditions, like memory running out. Normally there will
+ * be a yes or no to the request through the callback.
+ *
+ * \param permission The permission to request.
+ * \param cb The callback to trigger when the request has a response.
+ * \param userdata An app-controlled pointer that is passed to the callback.
+ * \returns zero if the request was submitted, -1 if there was an error
+ *          submitting. The result of the request is only ever reported
+ *          through the callback, not this return value.
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC int SDLCALL SDL_AndroidRequestPermissionAsync(const char *permission, SDL_AndroidRequestPermissionCallback cb, void *userdata);
+
 /**
  * Shows an Android toast notification.
  *