1 /* 2 * Copyright (C) 2019, The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 #pragma once 17 18 #include <stats_event.h> 19 20 #include <stdbool.h> 21 #include <stdint.h> 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * Opaque struct representing the metadata for registering an AStatsManager_PullAtomCallback. 29 */ 30 struct AStatsManager_PullAtomMetadata; 31 typedef struct AStatsManager_PullAtomMetadata AStatsManager_PullAtomMetadata; 32 33 /** 34 * Allocate and initialize new PullAtomMetadata. 35 * 36 * Must call AStatsManager_PullAtomMetadata_release to free the memory. 37 */ 38 AStatsManager_PullAtomMetadata* AStatsManager_PullAtomMetadata_obtain(); 39 40 /** 41 * Frees the memory held by this PullAtomMetadata 42 * 43 * After calling this, the PullAtomMetadata must not be used or modified in any way. 44 */ 45 void AStatsManager_PullAtomMetadata_release(AStatsManager_PullAtomMetadata* metadata); 46 47 /** 48 * Set the cool down time of the pull in milliseconds. If two successive pulls are issued 49 * within the cool down, a cached version of the first will be used for the second. The minimum 50 * allowed cool down is one second. 51 */ 52 void AStatsManager_PullAtomMetadata_setCoolDownMillis(AStatsManager_PullAtomMetadata* metadata, 53 int64_t cool_down_millis); 54 55 /** 56 * Get the cool down time of the pull in milliseconds. 57 */ 58 int64_t AStatsManager_PullAtomMetadata_getCoolDownMillis(AStatsManager_PullAtomMetadata* metadata); 59 60 /** 61 * Set the maximum time the pull can take in milliseconds. 62 * The maximum allowed timeout is 10 seconds. 63 */ 64 void AStatsManager_PullAtomMetadata_setTimeoutMillis(AStatsManager_PullAtomMetadata* metadata, 65 int64_t timeout_millis); 66 67 /** 68 * Get the maximum time the pull can take in milliseconds. 69 */ 70 int64_t AStatsManager_PullAtomMetadata_getTimeoutMillis(AStatsManager_PullAtomMetadata* metadata); 71 72 /** 73 * Set the additive fields of this pulled atom. 74 * 75 * This is only applicable for atoms which have a uid field. When tasks are run in 76 * isolated processes, the data will be attributed to the host uid. Additive fields 77 * will be combined when the non-additive fields are the same. 78 */ 79 void AStatsManager_PullAtomMetadata_setAdditiveFields(AStatsManager_PullAtomMetadata* metadata, 80 int32_t* additive_fields, int32_t num_fields); 81 82 /** 83 * Get the number of additive fields for this pulled atom. This is intended to be called before 84 * AStatsManager_PullAtomMetadata_getAdditiveFields to determine the size of the array. 85 */ 86 int32_t AStatsManager_PullAtomMetadata_getNumAdditiveFields( 87 AStatsManager_PullAtomMetadata* metadata); 88 89 /** 90 * Get the additive fields of this pulled atom. 91 * 92 * \param fields an output parameter containing the additive fields for this PullAtomMetadata. 93 * Fields is an array and it is assumed that it is at least as large as the number of 94 * additive fields, which can be obtained by calling 95 * AStatsManager_PullAtomMetadata_getNumAdditiveFields. 96 */ 97 void AStatsManager_PullAtomMetadata_getAdditiveFields(AStatsManager_PullAtomMetadata* metadata, 98 int32_t* fields); 99 100 /** 101 * Return codes for the result of a pull. 102 */ 103 typedef int32_t AStatsManager_PullAtomCallbackReturn; 104 enum { 105 // Value indicating that this pull was successful and that the result should be used. 106 AStatsManager_PULL_SUCCESS = 0, 107 // Value indicating that this pull was unsuccessful and that the result should not be used. 108 AStatsManager_PULL_SKIP = 1, 109 }; 110 111 /** 112 * Opaque struct representing a list of AStatsEvent objects. 113 */ 114 struct AStatsEventList; 115 typedef struct AStatsEventList AStatsEventList; 116 117 /** 118 * Appends and returns an AStatsEvent to the end of the AStatsEventList. 119 * 120 * If an AStatsEvent is obtained in this manner, the memory is internally managed and 121 * AStatsEvent_release does not need to be called. The lifetime of the AStatsEvent is that of the 122 * AStatsEventList. 123 * 124 * The AStatsEvent does still need to be built by calling AStatsEvent_build. 125 */ 126 AStatsEvent* AStatsEventList_addStatsEvent(AStatsEventList* pull_data); 127 128 /** 129 * Callback interface for pulling atoms requested by the stats service. 130 * 131 * \param atom_tag the tag of the atom to pull. 132 * \param data an output parameter in which the caller should fill the results of the pull. This 133 * param cannot be NULL and it's lifetime is as long as the execution of the callback. 134 * It must not be accessed or modified after returning from the callback. 135 * \param cookie the opaque pointer passed in AStatsManager_registerPullAtomCallback. 136 * \return AStatsManager_PULL_SUCCESS if the pull was successful, or AStatsManager_PULL_SKIP if not. 137 */ 138 typedef AStatsManager_PullAtomCallbackReturn (*AStatsManager_PullAtomCallback)( 139 int32_t atom_tag, AStatsEventList* data, void* cookie); 140 /** 141 * Sets a callback for an atom when that atom is to be pulled. The stats service will 142 * invoke the callback when the stats service determines that this atom needs to be 143 * pulled. 144 * 145 * Requires the REGISTER_STATS_PULL_ATOM permission. 146 * 147 * \param atom_tag The tag of the atom for this pull atom callback. 148 * \param metadata Optional metadata specifying the timeout, cool down time, and 149 * additive fields for mapping isolated to host uids. 150 * This param is nullable, in which case defaults will be used. 151 * \param callback The callback to be invoked when the stats service pulls the atom. 152 * \param cookie A pointer that will be passed back to the callback. 153 * It has no meaning to statsd. 154 */ 155 void AStatsManager_setPullAtomCallback(int32_t atom_tag, AStatsManager_PullAtomMetadata* metadata, 156 AStatsManager_PullAtomCallback callback, void* cookie); 157 158 /** 159 * Clears a callback for an atom when that atom is to be pulled. Note that any ongoing 160 * pulls will still occur. 161 * 162 * Requires the REGISTER_STATS_PULL_ATOM permission. 163 * 164 * \param atomTag The tag of the atom of which to unregister 165 */ 166 void AStatsManager_clearPullAtomCallback(int32_t atom_tag); 167 168 #ifdef __cplusplus 169 } 170 #endif 171