Proposed API for querying information about (e.g. shared) buffers.

mojo/public/c/system/buffer.h

 // Copyright 2014 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.
 
 // This file contains types/constants and functions specific to buffers (and in
 // particular shared buffers).
 // TODO(vtl): Reorganize this file (etc.) to separate general buffer functions
 // from (shared) buffer creation.
 //
 // Note: This header should be compilable as C.
@@ skipping 23 matching lines @@
 
 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int64_t) == 8, "int64_t has weird alignment");
 struct MOJO_ALIGNAS(8) MojoCreateSharedBufferOptions {
   uint32_t struct_size;
   MojoCreateSharedBufferOptionsFlags flags;
 };
 MOJO_STATIC_ASSERT(sizeof(MojoCreateSharedBufferOptions) == 8,
                    "MojoCreateSharedBufferOptions has wrong size");
 
 // |MojoDuplicateBufferHandleOptions|: Used to specify parameters in duplicating
-// access to a shared buffer to |MojoDuplicateBufferHandle()|.
+// access to a buffer to |MojoDuplicateBufferHandle()|.
 //   |uint32_t struct_size|: Set to the size of the
 //       |MojoDuplicateBufferHandleOptions| struct. (Used to allow for future
 //       extensions.)
 //   |MojoDuplicateBufferHandleOptionsFlags flags|: Reserved for future use.
 //       |MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE|: No flags; default
 //       mode.
 //
 // TODO(vtl): Add flags to remove writability (and executability)? Also, COW?
 
 typedef uint32_t MojoDuplicateBufferHandleOptionsFlags;
 
 #define MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE \
   ((MojoDuplicateBufferHandleOptionsFlags)0)
 
-struct MojoDuplicateBufferHandleOptions {
+struct MOJO_ALIGNAS(8) MojoDuplicateBufferHandleOptions {
   uint32_t struct_size;
   MojoDuplicateBufferHandleOptionsFlags flags;
 };
 MOJO_STATIC_ASSERT(sizeof(MojoDuplicateBufferHandleOptions) == 8,
                    "MojoDuplicateBufferHandleOptions has wrong size");
 
+// |MojoBufferInformation|: Used to provide information about a buffer (see
+// |MojoGetBufferInformation()|.
+//   |uint32_t struct_size|: Set to the size of the |MojoBufferInformation|
+//       struct. (Used to allow for future extensions.)
+//   |MojoBufferInformationFlags flags|: Reserved for future use.
+//   |uint64_t num_bytes|: Size of the buffer.
+//
+// TODO(vtl): Add flags to indicate writability, etc.? Also, type of buffer?
+
+typedef uint32_t MojoBufferInformationFlags;
+
+#define MOJO_BUFFER_INFORMATION_FLAG_NONE ((MojoBufferInformationFlags)0)
+
+struct MOJO_ALIGNAS(8) MojoBufferInformation {
+  uint32_t struct_size;
+  MojoBufferInformationFlags flags;
+  uint64_t num_bytes;
+};
+MOJO_STATIC_ASSERT(sizeof(MojoBufferInformation) == 16,
+                   "MojoBufferInformation has wrong size");
+
 // |MojoMapBufferFlags|: Used to specify different modes to |MojoMapBuffer()|.
 //   |MOJO_MAP_BUFFER_FLAG_NONE| - No flags; default mode.
 
 typedef uint32_t MojoMapBufferFlags;
 
 #define MOJO_MAP_BUFFER_FLAG_NONE ((MojoMapBufferFlags)0)
 
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ skipping 42 matching lines @@
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle or |*options| is invalid).
 //   |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
 MojoResult MojoDuplicateBufferHandle(
     MojoHandle buffer_handle,
     const struct MojoDuplicateBufferHandleOptions* options,  // Optional.
     MojoHandle* new_buffer_handle);                          // Out.
 
+// Gets information about the buffer with handle |buffer_handle|. |info| should
+// be non-null and point to a buffer of size |info_num_bytes|; |info_num_bytes|
+// should be at least 16 (the size of the first, and currently only, version of
+// |struct MojoBufferInformation|).
+//
+// On success, |*info| will be filled with information about the given buffer.
+// Note that if additional (larger) versions of |struct MojoBufferInformation|
+// are defined, the largest version permitted by |info_num_bytes| that is
+// supported by the implementation will be filled. Callers expecting more than
+// the first 16-byte version must check the resulting |info->struct_size|.
+//
+// Returns:
+//   |MOJO_RESULT_OK| on success.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
+//       |buffer_handle| is not a valid buffer handle, |*info| is null, or
+//       |info_num_bytes| is too small).
+MojoResult MojoGetBufferInformation(MojoHandle buffer_handle,
+                                    struct MojoBufferInformation* info,  // Out.
+                                    uint32_t info_num_bytes);            // In.
+
 // Maps the part (at offset |offset| of length |num_bytes|) of the buffer given
 // by |buffer_handle| into memory, with options specified by |flags|. |offset +
 // num_bytes| must be less than or equal to the size of the buffer. On success,
 // |*buffer| points to memory with the requested part of the buffer. (On
 // failure, it is not modified.)
 //
 // A single buffer handle may have multiple active mappings (possibly depending
 // on the buffer type). The permissions (e.g., writable or executable) of the
 // returned memory may depend on the properties of the buffer and properties
 // attached to the buffer handle as well as |flags|.
@@ skipping 24 matching lines @@
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |buffer| is invalid (e.g., is not the
 //       result of |MojoMapBuffer()| or has already been unmapped).
 MojoResult MojoUnmapBuffer(void* buffer);  // In.
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_BUFFER_H_