PPAPI: Add new PPB_FileRef.MakeDirectory to support exclusive operation

ppapi/api/ppb_file_ref.idl

Index: ppapi/api/ppb_file_ref.idl
diff --git a/ppapi/api/ppb_file_ref.idl b/ppapi/api/ppb_file_ref.idl
index d9226471a9f23cc6e9c862369ef905c25a9731b5..774f78aff3bc9b46cfa11975a7da407232f21fd9 100644
--- a/ppapi/api/ppb_file_ref.idl
+++ b/ppapi/api/ppb_file_ref.idl
@@ -10,7 +10,8 @@
 
 label Chrome {
   M14 = 1.0,
-  M28 = 1.1
+  M28 = 1.1,
+  [channel=dev] M34 = 1.2
 };
 
 /**
@@ -111,11 +112,37 @@ interface PPB_FileRef {
    * do not exist and <code>make_ancestors</code> was passed as
    * <code>PP_FALSE</code>.
    */
+  [deprecate=1.2]
   int32_t MakeDirectory([in] PP_Resource directory_ref,
                         [in] PP_Bool make_ancestors,
                         [in] PP_CompletionCallback callback);
 
   /**
+   * MakeDirectory() makes a new directory in the file system as well as any
+   * parent directories if the <code>make_ancestors</code> argument is
+   * <code>PP_TRUE</code>.  It is not valid to make a directory in the external
+   * file system.
+   *
+   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
+   * reference.
+   * @param[in] exclusive A <code>PP_Bool</code> set to <code>PP_TRUE</code> to
+   * fail if the directory already exists.
+   * @param[in] make_ancestors A <code>PP_Bool</code> set to
+   * <code>PP_TRUE</code> to make ancestor directories or <code>PP_FALSE</code>
+   * if ancestor directories are not needed.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Fails if the directory already exists and <code>exclusive</code> was passed
+   * as <code>PP_TRUE</code>.  And also fails if ancestor directories do not
+   * exist and <code>make_ancestors</code> was passed as <code>PP_FALSE</code>.
+   */
+  [version=1.2]
+  int32_t MakeDirectory([in] PP_Resource directory_ref,
+                        [in] PP_Bool exclusive,
+                        [in] PP_Bool make_ancestors,

[dmichael (off chromium), 2014/01/06 18:08:09]

At this point, might it make sense to move to a bit-field approach?

I'm a little concerned with having two consecutive parameters of the same type.
Especially since we're adding a new one (and adding it before the existing one).

A current plugin might have:
file_ref_if->MakeDirectory(dir_ref, PP_TRUE, callback);
When their compile breaks, they'll have to change to something like this to get
the same behavior:
file_ref_if->MakeDirectory(dir_ref, PP_FALSE, PP_TRUE, callback);
...but they could easily mess up and transpose the false/true. Same is true of
new code. It might be nicer if instead they changed to:

file_ref_if->MakeDirectory(dir_ref, PP_MAKE_DIRECTORY_WITH_ANCESTORS, callback);

It's maybe a shame that their C compiler might not warn them if they leave
PP_TRUE there. But as long as the "make_ancestors" bit is in the least
significant digit, it would actually work right (because PP_TRUE is fixed to 1).

Thoughts?

[yzshen1, 2014/01/06 18:44:11]

I like your idea. Thanks!
On 2014/01/06 18:08:09, dmichael wrote:

[nhiroki, 2014/01/07 07:32:45]

Good idea! Addressed it in the latest patchset.

+                        [in] PP_CompletionCallback callback);
+
+  /**
    * Touch() Updates time stamps for a file.  You must have write access to the
    * file if it exists in the external filesystem.
    *