| // 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); |
| } |