Index: ppapi/c/pp_completion_callback.h |
=================================================================== |
--- ppapi/c/pp_completion_callback.h (revision 91140) |
+++ ppapi/c/pp_completion_callback.h (working copy) |
@@ -21,8 +21,14 @@ |
*/ |
/** |
- * PP_CompletionCallback_Func defines the signature that you implement to |
+ * This typedef defines the signature that you implement to |
* receive callbacks on asynchronous completion. |
+ * |
+ * @param[in] user_data A pointer to user data passed to a callback function. |
+ * @param[in] result If result is 0 (PP_OK), the operation succeeded. Negative |
+ * values (other than -1) indicate error and are specified in pp_errors.h. |
+ * Positive values for result usually indicate success and have some |
+ * operation-dependent meaning (such as bytes read). |
*/ |
typedef void (*PP_CompletionCallback_Func)(void* user_data, int32_t result); |
/** |
@@ -35,22 +41,30 @@ |
*/ |
/** |
- * Any method that takes a PP_CompletionCallback has the option of completing |
- * asynchronously if the operation would block. Such a method should return |
- * PP_OK_COMPLETIONPENDING to indicate that the method will complete |
- * asynchronously and will always be invoked from the main thread of PPAPI |
- * execution. If the completion callback is NULL, then the operation will |
- * block if necessary to complete its work. PP_BlockUntilComplete() provides a |
- * convenient way to specify blocking behavior. Refer to PP_BlockUntilComplete |
- * for more information. |
+ * Any method that takes a <code>PP_CompletionCallback</code> has the option of |
+ * completing asynchronously if the operation would block. Such a method |
+ * should return <code>PP_OK_COMPLETIONPENDING</code> to indicate that the |
+ * method will complete asynchronously and will always be invoked from the main |
+ * thread of PPAPI execution. If the completion callback is NULL, then the |
+ * operation will block if necessary to complete its work. |
+ * <code>PP_BlockUntilComplete()</code> provides a convenient way to specify |
+ * blocking behavior. Refer to <code>PP_BlockUntilComplete</code> for more |
+ * information. |
* |
* The result parameter passes an int32_t that, if negative or equal to 0, |
- * indicate if the call will completely asynchronously (the callback will be |
+ * indicate if the call will complete asynchronously (the callback will be |
* called with a status code). A value greater than zero indicates additional |
* information such as bytes read. |
*/ |
struct PP_CompletionCallback { |
+ /** |
+ * This value is a callback function that will be called. |
+ */ |
PP_CompletionCallback_Func func; |
+ |
+ /** |
+ * This value is a pointer to user data passed to a callback function. |
+ */ |
void* user_data; |
}; |
/** |
@@ -63,13 +77,15 @@ |
*/ |
/** |
- * PP_MakeCompletionCallback() is used to create a PP_CompletionCallback. |
+ * PP_MakeCompletionCallback() is used to create a |
+ * <code>PP_CompletionCallback</code>. |
* |
- * @param[in] func A PP_CompletionCallback_Func that will be called. |
+ * @param[in] func A <code>PP_CompletionCallback_Func</code> that will be |
+ * called. |
* @param[in] user_data A pointer to user data passed to your callback |
* function. This is optional and is typically used to help track state |
* when you may have multiple callbacks pending. |
- * @return A PP_CompletionCallback structure. |
+ * @return A <code>PP_CompletionCallback</code> structure. |
*/ |
PP_INLINE struct PP_CompletionCallback PP_MakeCompletionCallback( |
PP_CompletionCallback_Func func, |
@@ -91,7 +107,8 @@ |
/** |
* PP_RunCompletionCallback() is used to run a callback. |
* |
- * @param[in] cc A pointer to a PP_CompletionCallback that will be run. |
+ * @param[in] cc A pointer to a <code>PP_CompletionCallback</code> that will be |
+ * run. |
* @param[in] res The result parameter that, if negative or equal to 0, |
* indicate if the call will completely asynchronously (the callback will be |
* called with a status code). A value greater than zero indicates additional |
@@ -117,24 +134,24 @@ |
* until the function completes. Blocking completion callbacks are only usable |
* from background threads. |
* |
- * @return A PP_CompletionCallback structure. |
+ * @return A <code>PP_CompletionCallback</code> structure. |
*/ |
PP_INLINE struct PP_CompletionCallback PP_BlockUntilComplete() { |
return PP_MakeCompletionCallback(NULL, NULL); |
} |
/** |
- * Runs a callback and clears the reference to it. |
+ * PP_RunAndClearCompletionCallback() runs a callback and clears the reference |
+ * to that callback. |
* |
- * This is used when the null-ness of a completion callback is used as a signal |
- * for whether a completion callback has been registered. In this case, after |
- * the execution of the callback, it should be cleared. |
- * |
- * However, this introduces a conflict if the completion callback wants to |
- * schedule more work that involves the same completion callback again (for |
- * example, when reading data from an URLLoader, one would typically queue up |
+ * This function is used when the null-ness of a completion callback is used as |
+ * a signal for whether a completion callback has been registered. In this |
+ * case, after the execution of the callback, it should be cleared. However, |
+ * this introduces a conflict if the completion callback wants to schedule more |
+ * work that involves the same completion callback again (for example, when |
+ * reading data from an URLLoader, one would typically queue up |
* another read callback). As a result, this function clears the pointer |
- * *before* the given callback is executed. |
+ * before the provided callback is executed. |
*/ |
PP_INLINE void PP_RunAndClearCompletionCallback( |
struct PP_CompletionCallback* cc, |