changes for proxy audio

ppapi/c/dev/ppb_audio_trusted_dev.h

 // Copyright (c) 2010 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef PPAPI_C_DEV_PPB_AUDIO_TRUSTED_DEV_H_
 #define PPAPI_C_DEV_PPB_AUDIO_TRUSTED_DEV_H_
 
+#include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_resource.h"
 
-#define PPB_AUDIO_TRUSTED_DEV_INTERFACE "PPB_AudioTrusted(Dev);0.1"
+#define PPB_AUDIO_TRUSTED_DEV_INTERFACE "PPB_AudioTrusted(Dev);0.2"
 
-// This interface is used to get access to the audio buffer and a socket on
-// which the client can block until the audio is ready to accept more data.
-// This interface should be used by NaCl to implement the Audio interface.
+// This callback is invoked during StreamCreated() from the main thead,

[darin (slow to review), 2010/11/19 17:45:39]

this comment refers to chromium implementation specific things.  this API
shouldn't be chromium specific, so you should probably simplify this comment. 
it is valuable to say that the callback is run on the main thread.

+// enabling the access to the handles needed for proxied audio.
+// Returns PP_TRUE on success.
+typedef PP_Bool (*PPB_AudioTrusted_Callback)(PP_Instance pp_instance,

[darin (slow to review), 2010/11/19 17:45:39]

nit: PP_ instead of PPB_

PPB_ is reserved for interfaces implemented by the browser.

[darin (slow to review), 2010/11/19 17:45:39]

nit: we usually don't use the prefix "pp_" in variable names in the "c" headers

+                                             PP_Resource pp_audio,
+                                             int64_t shared_memory_handle,

[darin (slow to review), 2010/11/19 17:45:39]

int64_t -> uint64_t like PPB_ImageData_Trusted?

+                                             size_t shared_memory_size,
+                                             int64_t socket_handle);

[darin (slow to review), 2010/11/19 17:45:39]

why is socket_handle int64_t?  shouldn't it just be an "int" since it is a file
descriptor?

+
+// This interface is to be used by proxy implementations.
 struct PPB_AudioTrusted_Dev {

[darin (slow to review), 2010/11/19 17:45:39]

As discussed in person, I think the API would be better like this:

  struct PPB_AudioTrusted_Dev {
    PP_Resource (*Create)(PP_Instance);

    int32_t (*Open)(PP_Resource audio,
                    PP_Resource config,
                    PP_CompletionCallback callback);
    void (*Close)(PP_Resource audio);

    uint64_t (*GetNativeMemoryHandle)(PP_Resource audio,
                                      uint32_t* byte_count);
    int (*GetSynchronizationSocket)(PP_Resource audio);
  };

This gives you several benefits:

1- Uses CompletionCallback for consistency.
2- Close may be used to interrupt an Open that hasn't completed.  Releasing the
last reference to the audio resource would implicitly close it.
3- GetNativeMemoryHandle is consistent with PPB_ImageData_Trusted.
4- GetSynchronizationSocket makes it more clear what the socket handle is that
you are getting back.

-  // Returns a Buffer object that has the audio buffer.
-  PP_Resource (*GetBuffer)(PP_Resource audio);
-
-  // Returns a select()-able/Wait()-able OS-specific descriptor. The browser
-  // will put a byte on the socket each time the buffer is ready to be filled.
-  // The plugin can then implement its own audio thread using select()/poll() to
-  // block until the browser is ready to receive data.
-  int (*GetOSDescriptor)(PP_Resource audio);
+  // Creates a paused audio interface, used by trusted side of proxy.
+  // It returns an audio resource, so the remaining functionality
+  // can be accessed through the PPB_Audio_Dev interface.
+  PP_Resource (*Create)(PP_Instance instance, PP_Resource config,
+      PPB_AudioTrusted_Callback create_callback);

[darin (slow to review), 2010/11/19 17:45:39]

nit: please indent this line so that you have:

  PP_Resource (*Create)(PP_Instance instance, PP_Resource config,
                        PPB_AudioTrusted_Callback create_callback);

 };
 
 #endif  // PPAPI_C_DEV_PPB_AUDIO_TRUSTED_DEV_H_
-