[apple/libdispatch.git] / os / voucher_activity_private.h

/*
 * Copyright (c) 2013-2015 Apple Inc. All rights reserved.
 *
 * @APPLE_APACHE_LICENSE_HEADER_START@
 *
 * 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.
 *
 * @APPLE_APACHE_LICENSE_HEADER_END@
 */

#ifndef __OS_VOUCHER_ACTIVITY_PRIVATE__
#define __OS_VOUCHER_ACTIVITY_PRIVATE__

#if OS_VOUCHER_ACTIVITY_SPI
#if __has_include(<mach/mach_time.h>)
#include <mach/mach_time.h>
#include <firehose/tracepoint_private.h>
#endif
#ifndef __linux__
#include <os/base.h>
#include <os/availability.h>
#endif
#include <sys/uio.h>
#include <os/object.h>
#include "voucher_private.h"

#define OS_VOUCHER_ACTIVITY_SPI_VERSION 20161003

#if OS_VOUCHER_WEAK_IMPORT
#define OS_VOUCHER_EXPORT OS_EXPORT OS_WEAK_IMPORT
#else
#define OS_VOUCHER_EXPORT OS_EXPORT
#endif

__BEGIN_DECLS

/*!
 * @const VOUCHER_CURRENT
 * Shorthand for the currently adopted voucher
 *
 * This value can only be used as an argument to functions, and is never
 * actually returned. It looks enough like a tagged pointer object that ARC
 * won't crash if this is assigned to a temporary variable.
 */
#define VOUCHER_CURRENT		((OS_OBJECT_BRIDGE voucher_t)(void *)~2ul)

/*!
 * @function voucher_get_activity_id
 *
 * @abstract
 * Returns the activity_id associated with the specified voucher at the time
 * of the call.
 *
 * @discussion
 * When the passed voucher is VOUCHER_CURRENT this returns the current
 * activity ID.
 *
 * @param voucher
 * The specified voucher.
 *
 * @param parent_id
 * An out parameter to return the parent ID of the returned activity ID.
 *
 * @result
 * The current activity identifier, if any. When 0 is returned, parent_id will
 * also always be 0.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
OS_VOUCHER_EXPORT OS_NOTHROW
firehose_activity_id_t
voucher_get_activity_id(voucher_t voucher, firehose_activity_id_t *parent_id);

/*!
 * @function voucher_get_activity_id_and_creator
 *
 * @abstract
 * Returns the activity_id associated with the specified voucher at the time
 * of the call.
 *
 * @discussion
 * When the passed voucher is VOUCHER_CURRENT this returns the current
 * activity ID.
 *
 * @param voucher
 * The specified voucher.
 *
 * @param creator_pid
 * The unique pid of the process that created the returned activity ID if any.
 *
 * @param parent_id
 * An out parameter to return the parent ID of the returned activity ID.
 *
 * @result
 * The current activity identifier, if any. When 0 is returned, parent_id will
 * also always be 0.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
OS_VOUCHER_EXPORT OS_NOTHROW
firehose_activity_id_t
voucher_get_activity_id_and_creator(voucher_t voucher, uint64_t *creator_pid,
		firehose_activity_id_t *parent_id);

/*!
 * @function voucher_activity_create_with_data
 *
 * @abstract
 * Creates a voucher object with a new activity identifier.
 *
 * @discussion
 * As part of voucher transport, activities are automatically propagated by the
 * system to other threads and processes (across IPC).
 *
 * When a voucher with an activity identifier is applied to a thread, work
 * on that thread is done on behalf of this activity.
 *
 * @param trace_id
 * Tracepoint identifier returned by voucher_activity_trace_id(), intended for
 * identification of the automatic tracepoint generated as part of creating the
 * new activity.
 *
 * @param base
 * The base voucher used to create the activity. If the base voucher has an
 * activity identifier, then the created activity will be parented to that one.
 * If the passed in base has no activity identifier, the activity identifier
 * will be a top-level one, on behalf of the process that created the base
 * voucher.
 *
 * If base is VOUCHER_NONE, the activity is a top-level one, on behalf of the
 * current process.
 *
 * If base is VOUCHER_CURRENT, then the activity is naturally based on the
 * one currently applied to the current thread (the one voucher_copy() would
 * return).
 *
 * @param flags
 * See voucher_activity_flag_t documentation for effect.
 *
 * @param pubdata
 * Pointer to packed buffer of tracepoint data.
 *
 * @param publen
 * Length of data at 'pubdata'.
 *
 * @result
 * A new voucher with an activity identifier.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
voucher_t
voucher_activity_create_with_data(firehose_tracepoint_id_t *trace_id,
		voucher_t base, firehose_activity_flags_t flags,
		const void *pubdata, size_t publen);

API_DEPRECATED_WITH_REPLACEMENT("voucher_activity_create_with_data",
		macos(10.12,10.12), ios(10.0,10.0), tvos(10.0,10.0), watchos(3.0,3.0))
OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
voucher_t
voucher_activity_create_with_location(firehose_tracepoint_id_t *trace_id,
		voucher_t base, firehose_activity_flags_t flags, uint64_t location);

/*!
 * @group Voucher Activity Trace SPI
 * SPI intended for libtrace only
 */

/*!
 * @function voucher_activity_id_allocate
 *
 * @abstract
 * Allocate a new system-wide unique activity ID.
 *
 * @param flags
 * The bottom-most 8 bits of the flags will be used to generate the ID.
 * See firehose_activity_flags_t.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
OS_VOUCHER_EXPORT OS_NOTHROW
firehose_activity_id_t
voucher_activity_id_allocate(firehose_activity_flags_t flags);

/*!
 * @function voucher_activity_flush
 *
 * @abstract
 * Force flushing the specified stream.
 *
 * @discussion
 * This maks all the buffers currently being written to as full, so that
 * their current content is pushed in a timely fashion.
 *
 * When this call returns, the actual flush may or may not yet have happened.
 *
 * @param stream
 * The stream to flush.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
OS_VOUCHER_EXPORT OS_NOTHROW
void
voucher_activity_flush(firehose_stream_t stream);

/*!
 * @function voucher_activity_trace
 *
 * @abstract
 * Add a tracepoint to the specified stream.
 *
 * @param stream
 * The stream to trace this entry into.
 *
 * @param trace_id
 * Tracepoint identifier returned by voucher_activity_trace_id()
 *
 * @param timestamp
 * The mach_approximate_time()/mach_absolute_time() value for this tracepoint.
 *
 * @param pubdata
 * Pointer to packed buffer of tracepoint data.
 *
 * @param publen
 * Length of data at 'pubdata'.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL4
firehose_tracepoint_id_t
voucher_activity_trace(firehose_stream_t stream,
		firehose_tracepoint_id_t trace_id, uint64_t timestamp,
		const void *pubdata, size_t publen);

/*!
 * @function voucher_activity_trace_v
 *
 * @abstract
 * Add a tracepoint to the specified stream, with private data.
 *
 * @param stream
 * The stream to trace this entry into.
 *
 * @param trace_id
 * Tracepoint identifier returned by voucher_activity_trace_id()
 *
 * @param timestamp
 * The mach_approximate_time()/mach_absolute_time() value for this tracepoint.
 *
 * @param iov
 * Array of `struct iovec` pointing to the data to layout.
 * The total size of this iovec must span exactly `publen + privlen` bytes.
 * The `publen` boundary must coincide with the end of an iovec (each iovec
 * must either be pure public or pure private data).
 *
 * @param publen
 * Total length of data to read from the iovec for the public data.
 *
 * @param privlen
 * Length of data to read from the iovec after the public data for the private
 * data.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL4
firehose_tracepoint_id_t
voucher_activity_trace_v(firehose_stream_t stream,
		firehose_tracepoint_id_t trace_id, uint64_t timestamp,
		const struct iovec *iov, size_t publen, size_t privlen);


API_DEPRECATED_WITH_REPLACEMENT("voucher_activity_trace_v",
		macos(10.12,10.12), ios(10.0,10.0), tvos(10.0,10.0), watchos(3.0,3.0))
OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL4 OS_NONNULL6
firehose_tracepoint_id_t
voucher_activity_trace_with_private_strings(firehose_stream_t stream,
		firehose_tracepoint_id_t trace_id, uint64_t timestamp,
		const void *pubdata, size_t publen,
		const void *privdata, size_t privlen);

typedef const struct voucher_activity_hooks_s {
#define VOUCHER_ACTIVITY_HOOKS_VERSION     5
	long vah_version;
	mach_port_t (*vah_get_logd_port)(void);
	dispatch_mach_handler_function_t vah_debug_channel_handler;
	kern_return_t (*vah_get_reconnect_info)(mach_vm_address_t *, mach_vm_size_t *);
	void (*vah_metadata_init)(void *metadata_buffer, size_t size);
	void (*vah_quarantine_starts)(void);
} *voucher_activity_hooks_t;

/*!
 * @function voucher_activity_initialize_4libtrace
 *
 * @abstract
 * Configure upcall hooks for libtrace.
 *
 * @param hooks
 * A pointer to a voucher_activity_hooks_s structure.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL_ALL
void
voucher_activity_initialize_4libtrace(voucher_activity_hooks_t hooks);

/*!
 * @function voucher_activity_get_metadata_buffer
 *
 * @abstract
 * Return address and length of buffer in the process trace memory area
 * reserved for libtrace metadata.
 *
 * @param length
 * Pointer to size_t variable, filled with length of metadata buffer.
 *
 * @result
 * Address of metadata buffer.
 */
API_AVAILABLE(macos(10.10), ios(8.0))
OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL_ALL
void*
voucher_activity_get_metadata_buffer(size_t *length);

/*!
 * @function voucher_get_activity_id_4dyld
 *
 * @abstract
 * Return the current voucher activity ID. Available for the dyld client stub
 * only.
 */
API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW
firehose_activity_id_t
voucher_get_activity_id_4dyld(void);

__END_DECLS

#endif // OS_VOUCHER_ACTIVITY_SPI

#endif // __OS_VOUCHER_ACTIVITY_PRIVATE__
Commit	Line	Data
beb15981 A	1	/*
	2	* Copyright (c) 2013-2015 Apple Inc. All rights reserved.
	3	*
	4	* @APPLE_APACHE_LICENSE_HEADER_START@
	5	*
	6	* Licensed under the Apache License, Version 2.0 (the "License");
	7	* you may not use this file except in compliance with the License.
	8	* You may obtain a copy of the License at
	9	*
	10	* http://www.apache.org/licenses/LICENSE-2.0
	11	*
	12	* Unless required by applicable law or agreed to in writing, software
	13	* distributed under the License is distributed on an "AS IS" BASIS,
	14	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	15	* See the License for the specific language governing permissions and
	16	* limitations under the License.
	17	*
	18	* @APPLE_APACHE_LICENSE_HEADER_END@
	19	*/
	20
	21	#ifndef __OS_VOUCHER_ACTIVITY_PRIVATE__
	22	#define __OS_VOUCHER_ACTIVITY_PRIVATE__
	23
	24	#if OS_VOUCHER_ACTIVITY_SPI
	25	#if __has_include(<mach/mach_time.h>)
	26	#include <mach/mach_time.h>
	27	#include <firehose/tracepoint_private.h>
	28	#endif
	29	#ifndef __linux__
	30	#include <os/base.h>
6b746eb4	31	#include <os/availability.h>
beb15981	32	#endif
fa22f35b	33	#include <sys/uio.h>
beb15981 A	34	#include <os/object.h>
	35	#include "voucher_private.h"
	36
fa22f35b	37	#define OS_VOUCHER_ACTIVITY_SPI_VERSION 20161003
beb15981 A	38
	39	#if OS_VOUCHER_WEAK_IMPORT
	40	#define OS_VOUCHER_EXPORT OS_EXPORT OS_WEAK_IMPORT
	41	#else
	42	#define OS_VOUCHER_EXPORT OS_EXPORT
	43	#endif
	44
beb15981 A	45	__BEGIN_DECLS
	46
	47	/*!
	48	* @const VOUCHER_CURRENT
	49	* Shorthand for the currently adopted voucher
	50	*
	51	* This value can only be used as an argument to functions, and is never
	52	* actually returned. It looks enough like a tagged pointer object that ARC
	53	* won't crash if this is assigned to a temporary variable.
	54	*/
	55	#define VOUCHER_CURRENT ((OS_OBJECT_BRIDGE voucher_t)(void *)~2ul)
	56
	57	/*!
	58	* @function voucher_get_activity_id
	59	*
	60	* @abstract
	61	* Returns the activity_id associated with the specified voucher at the time
	62	* of the call.
	63	*
	64	* @discussion
	65	* When the passed voucher is VOUCHER_CURRENT this returns the current
	66	* activity ID.
	67	*
	68	* @param voucher
	69	* The specified voucher.
	70	*
	71	* @param parent_id
	72	* An out parameter to return the parent ID of the returned activity ID.
	73	*
	74	* @result
	75	* The current activity identifier, if any. When 0 is returned, parent_id will
	76	* also always be 0.
	77	*/
6b746eb4	78	API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
beb15981 A	79	OS_VOUCHER_EXPORT OS_NOTHROW
	80	firehose_activity_id_t
	81	voucher_get_activity_id(voucher_t voucher, firehose_activity_id_t *parent_id);
	82
	83	/*!
	84	* @function voucher_get_activity_id_and_creator
	85	*
	86	* @abstract
	87	* Returns the activity_id associated with the specified voucher at the time
	88	* of the call.
	89	*
	90	* @discussion
	91	* When the passed voucher is VOUCHER_CURRENT this returns the current
	92	* activity ID.
	93	*
	94	* @param voucher
	95	* The specified voucher.
	96	*
	97	* @param creator_pid
	98	* The unique pid of the process that created the returned activity ID if any.
	99	*
	100	* @param parent_id
	101	* An out parameter to return the parent ID of the returned activity ID.
	102	*
	103	* @result
	104	* The current activity identifier, if any. When 0 is returned, parent_id will
	105	* also always be 0.
	106	*/
6b746eb4	107	API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
beb15981 A	108	OS_VOUCHER_EXPORT OS_NOTHROW
	109	firehose_activity_id_t
	110	voucher_get_activity_id_and_creator(voucher_t voucher, uint64_t *creator_pid,
	111	firehose_activity_id_t *parent_id);
	112
	113	/*!
fa22f35b	114	* @function voucher_activity_create_with_data
beb15981 A	115	*
	116	* @abstract
	117	* Creates a voucher object with a new activity identifier.
	118	*
	119	* @discussion
	120	* As part of voucher transport, activities are automatically propagated by the
	121	* system to other threads and processes (across IPC).
	122	*
	123	* When a voucher with an activity identifier is applied to a thread, work
	124	* on that thread is done on behalf of this activity.
	125	*
	126	* @param trace_id
	127	* Tracepoint identifier returned by voucher_activity_trace_id(), intended for
	128	* identification of the automatic tracepoint generated as part of creating the
	129	* new activity.
	130	*
	131	* @param base
	132	* The base voucher used to create the activity. If the base voucher has an
	133	* activity identifier, then the created activity will be parented to that one.
	134	* If the passed in base has no activity identifier, the activity identifier
	135	* will be a top-level one, on behalf of the process that created the base
	136	* voucher.
	137	*
	138	* If base is VOUCHER_NONE, the activity is a top-level one, on behalf of the
	139	* current process.
	140	*
	141	* If base is VOUCHER_CURRENT, then the activity is naturally based on the
	142	* one currently applied to the current thread (the one voucher_copy() would
	143	* return).
	144	*
	145	* @param flags
	146	* See voucher_activity_flag_t documentation for effect.
	147	*
fa22f35b A	148	* @param pubdata
	149	* Pointer to packed buffer of tracepoint data.
	150	*
	151	* @param publen
	152	* Length of data at 'pubdata'.
beb15981 A	153	*
	154	* @result
	155	* A new voucher with an activity identifier.
	156	*/
6b746eb4	157	API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
beb15981 A	158	OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
beb15981 A	159	voucher_t
fa22f35b A	160	voucher_activity_create_with_data(firehose_tracepoint_id_t *trace_id,
	161	voucher_t base, firehose_activity_flags_t flags,
	162	const void *pubdata, size_t publen);
beb15981	163
6b746eb4 A	164	API_DEPRECATED_WITH_REPLACEMENT("voucher_activity_create_with_data",
6b746eb4 A	165	macos(10.12,10.12), ios(10.0,10.0), tvos(10.0,10.0), watchos(3.0,3.0))
beb15981 A	166	OS_VOUCHER_EXPORT OS_OBJECT_RETURNS_RETAINED OS_WARN_RESULT OS_NOTHROW
	167	voucher_t
	168	voucher_activity_create_with_location(firehose_tracepoint_id_t *trace_id,
	169	voucher_t base, firehose_activity_flags_t flags, uint64_t location);
	170
	171	/*!
	172	* @group Voucher Activity Trace SPI
	173	* SPI intended for libtrace only
	174	*/
	175
6b746eb4 A	176	/*!
	177	* @function voucher_activity_id_allocate
	178	*
	179	* @abstract
	180	* Allocate a new system-wide unique activity ID.
	181	*
	182	* @param flags
	183	* The bottom-most 8 bits of the flags will be used to generate the ID.
	184	* See firehose_activity_flags_t.
	185	*/
	186	API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
	187	OS_VOUCHER_EXPORT OS_NOTHROW
	188	firehose_activity_id_t
	189	voucher_activity_id_allocate(firehose_activity_flags_t flags);
	190
beb15981 A	191	/*!
	192	* @function voucher_activity_flush
	193	*
	194	* @abstract
	195	* Force flushing the specified stream.
	196	*
	197	* @discussion
	198	* This maks all the buffers currently being written to as full, so that
	199	* their current content is pushed in a timely fashion.
	200	*
	201	* When this call returns, the actual flush may or may not yet have happened.
	202	*
	203	* @param stream
	204	* The stream to flush.
	205	*/
6b746eb4	206	API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
beb15981 A	207	OS_VOUCHER_EXPORT OS_NOTHROW
	208	void
	209	voucher_activity_flush(firehose_stream_t stream);
	210
	211	/*!
	212	* @function voucher_activity_trace
	213	*
	214	* @abstract
	215	* Add a tracepoint to the specified stream.
	216	*
	217	* @param stream
	218	* The stream to trace this entry into.
	219	*
	220	* @param trace_id
	221	* Tracepoint identifier returned by voucher_activity_trace_id()
	222	*
	223	* @param timestamp
	224	* The mach_approximate_time()/mach_absolute_time() value for this tracepoint.
	225	*
	226	* @param pubdata
	227	* Pointer to packed buffer of tracepoint data.
	228	*
	229	* @param publen
	230	* Length of data at 'pubdata'.
	231	*/
6b746eb4	232	API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
beb15981 A	233	OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL4
	234	firehose_tracepoint_id_t
	235	voucher_activity_trace(firehose_stream_t stream,
	236	firehose_tracepoint_id_t trace_id, uint64_t timestamp,
	237	const void *pubdata, size_t publen);
	238
	239	/*!
fa22f35b	240	* @function voucher_activity_trace_v
beb15981 A	241	*
	242	* @abstract
	243	* Add a tracepoint to the specified stream, with private data.
	244	*
	245	* @param stream
	246	* The stream to trace this entry into.
	247	*
	248	* @param trace_id
	249	* Tracepoint identifier returned by voucher_activity_trace_id()
	250	*
	251	* @param timestamp
	252	* The mach_approximate_time()/mach_absolute_time() value for this tracepoint.
	253	*
fa22f35b A	254	* @param iov
	255	* Array of `struct iovec` pointing to the data to layout.
	256	* The total size of this iovec must span exactly `publen + privlen` bytes.
	257	* The `publen` boundary must coincide with the end of an iovec (each iovec
	258	* must either be pure public or pure private data).
beb15981 A	259	*
beb15981 A	260	* @param publen
fa22f35b	261	* Total length of data to read from the iovec for the public data.
beb15981 A	262	*
beb15981 A	263	* @param privlen
fa22f35b A	264	* Length of data to read from the iovec after the public data for the private
fa22f35b A	265	* data.
beb15981	266	*/
6b746eb4	267	API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
fa22f35b A	268	OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL4
	269	firehose_tracepoint_id_t
	270	voucher_activity_trace_v(firehose_stream_t stream,
	271	firehose_tracepoint_id_t trace_id, uint64_t timestamp,
	272	const struct iovec *iov, size_t publen, size_t privlen);
	273
	274
6b746eb4 A	275	API_DEPRECATED_WITH_REPLACEMENT("voucher_activity_trace_v",
6b746eb4 A	276	macos(10.12,10.12), ios(10.0,10.0), tvos(10.0,10.0), watchos(3.0,3.0))
beb15981 A	277	OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL4 OS_NONNULL6
	278	firehose_tracepoint_id_t
	279	voucher_activity_trace_with_private_strings(firehose_stream_t stream,
	280	firehose_tracepoint_id_t trace_id, uint64_t timestamp,
	281	const void *pubdata, size_t publen,
	282	const void *privdata, size_t privlen);
	283
fa22f35b	284	typedef const struct voucher_activity_hooks_s {
6b746eb4	285	#define VOUCHER_ACTIVITY_HOOKS_VERSION 5
beb15981	286	long vah_version;
beb15981	287	mach_port_t (*vah_get_logd_port)(void);
beb15981	288	dispatch_mach_handler_function_t vah_debug_channel_handler;
beb15981	289	kern_return_t (vah_get_reconnect_info)(mach_vm_address_t , mach_vm_size_t *);
fa22f35b	290	void (vah_metadata_init)(void metadata_buffer, size_t size);
6b746eb4	291	void (*vah_quarantine_starts)(void);
beb15981 A	292	} *voucher_activity_hooks_t;
	293
	294	/*!
	295	* @function voucher_activity_initialize_4libtrace
	296	*
	297	* @abstract
	298	* Configure upcall hooks for libtrace.
	299	*
	300	* @param hooks
	301	* A pointer to a voucher_activity_hooks_s structure.
	302	*/
6b746eb4	303	API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
beb15981 A	304	OS_VOUCHER_EXPORT OS_NOTHROW OS_NONNULL_ALL
	305	void
	306	voucher_activity_initialize_4libtrace(voucher_activity_hooks_t hooks);
	307
	308	/*!
	309	* @function voucher_activity_get_metadata_buffer
	310	*
	311	* @abstract
	312	* Return address and length of buffer in the process trace memory area
	313	* reserved for libtrace metadata.
	314	*
	315	* @param length
	316	* Pointer to size_t variable, filled with length of metadata buffer.
	317	*
	318	* @result
	319	* Address of metadata buffer.
	320	*/
6b746eb4	321	API_AVAILABLE(macos(10.10), ios(8.0))
beb15981 A	322	OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW OS_NONNULL_ALL
	323	void*
	324	voucher_activity_get_metadata_buffer(size_t *length);
	325
	326	/*!
	327	* @function voucher_get_activity_id_4dyld
	328	*
	329	* @abstract
	330	* Return the current voucher activity ID. Available for the dyld client stub
	331	* only.
	332	*/
6b746eb4	333	API_AVAILABLE(macos(10.12), ios(10.0), tvos(10.0), watchos(3.0))
beb15981 A	334	OS_VOUCHER_EXPORT OS_WARN_RESULT OS_NOTHROW
	335	firehose_activity_id_t
	336	voucher_get_activity_id_4dyld(void);
	337
	338	__END_DECLS
	339
	340	#endif // OS_VOUCHER_ACTIVITY_SPI
	341
	342	#endif // __OS_VOUCHER_ACTIVITY_PRIVATE__