// Copyright 2012 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// Defines the Call Trace Service RPC interface.
[
    uuid(4BDE4DEF-DE55-49f2-940D-9B2DE5F65B00),
    version(1.0)
]
interface CallTrace {
  // Used to track server side resources allocated on behalf of the client.
  typedef [context_handle] void* SessionHandle;

  typedef struct {
    // The shared memory mapped file handle that will be duplicated into the
    // client's address space. A shared file object will be created by the
    // server and the client should (on first receipt of a buffer with this
    // handle) perform a ::MapViewOfFile() to get the corresponding
    // local base addreess of the memory mapped file. Multiple
    // CallTraceBuffer objects may share the same shared_memory_handle
    // value. The pair {shared_memory_handle, buffer_offset} uniquely
    // identifies a buffer.
    unsigned long shared_memory_handle;

    // The total size (in bytes) of the shared memory buffer.
    unsigned long mapping_size;

    // The byte offset [from the base pointer returned by ::MapViewOfFile()]
    // at which this buffer begins.
    unsigned long buffer_offset;

    // The maximum size (in bytes) of the buffer.
    unsigned long buffer_size;
  } CallTraceBuffer;

  // Create a new CallTrace session.
  //
  // @param binding The RPC binding of the client. The binding is obtained
  //     by calling ::RpcStringBindingCompose() with the appropriate protocol
  //     and endpoint strings, followed by ::RpcBindingFromStringBinding().
  // @param command_line The UTF-16 command line of the process.
  // @param session_handle On success, returns the session handle.
  // @param call_trace_buffer On success, this CallTraceBuffer structure will
  //     be populated with a valid buffer description.
  // @param flags On success, the service will return the currently configured
  //     call trace flags here.
  boolean CreateSession([in] handle_t binding,
                        [out] SessionHandle* session_handle,
                        [out] CallTraceBuffer* call_trace_buffer,
                        [out] unsigned long* flags);

  // Allocate a call trace buffer.
  //
  // This function should be called when a newly created client thread needs
  // to acquire its first call trace buffer. Once a thread has a call trace
  // buffer, it should use the ExchangeBuffer function to commit that buffer
  // and receive a fresh one.
  //
  // @param session_handle The handle used to identify the client.
  // @param call_trace_buffer The CallTraceBuffer structure to populate.
  boolean AllocateBuffer([in] SessionHandle session_handle,
                         [out] CallTraceBuffer* call_trace_buffer);

  // Allocate a large persistent call trace buffer.
  //
  // This function should be called when a newly created client thread needs to
  // acquire a larger than usual buffer. This function is not throttled so
  // should only be used for buffers that have process lifespan. They should be
  // returned using the normal ExchangeBuffer or ReturnBuffer mechanism.
  //
  // @param session_handle The handle used to identify the client.
  // @param minimum_size the minimum size of the buffer to be returned.
  // @param call_trace_buffer The CallTraceBuffer structure to populate.
  boolean AllocateLargeBuffer([in] SessionHandle session_handle,
                              [in] unsigned long minimum_size,
                              [out] CallTraceBuffer* call_trace_buffer);

  // Commit a CallTraceBuffer and get a fresh one to continue writing to.
  //
  // This function should be called when a client thread exhausts its current
  // call trace buffer and needs a fresh one... i.e., when the next event the
  // client is about to write would overflow the current buffer.
  //
  // No reference to copies of the passed in CallTraceBuffer's data should
  // be retained by the client.  This operation is a swap; ownership of the
  // client's current CallTraceBuffer will pass to the CallTrace service,
  // and the information for a new CallTraceBuffer will be written into the
  // *call_trace_buffer structure.
  //
  // @param session_handle The handle used to identify the client.
  // @param call_trace_buffer The CallTraceBuffer to swap for a fresh one.
  boolean ExchangeBuffer([in] SessionHandle session_handle,
                         [in, out] CallTraceBuffer* call_trace_buffer);

  // Commit a CallTraceBuffer without getting a fresh one.
  //
  // This function should be called when a thread exits in order to free up
  // resources within the CallTrace Service.
  //
  // No reference to copies of the passed in CallTraceBuffer's data should
  // be retained by the client.  This operation is a release; ownership of
  // the client's current CallTraceBuffer will pass to the CallTrace service,
  // and the information for the old CallTraceBuffer will be cleared from the
  // *call_trace_buffer structure.
  //
  // @param session_handle The handle used to identify the client.
  // @param call_trace_buffer The CallTraceBuffer to release.
  boolean ReturnBuffer([in] SessionHandle session_handle,
                       [in, out] CallTraceBuffer* call_trace_buffer);

  // Close a session and commit any outstanding buffers.
  //
  // @param session_handle The handle used to identify the client.
  boolean CloseSession([in, out] SessionHandle* session_handle);
}

[
  uuid(888783EC-8ADD-41bf-BD1D-CE8CC7D095A8),
  version(1.0)
]
interface CallTraceControl {
  // Request a shutdown of the call trace service.
  boolean Stop([in] handle_t binding);
}