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 17 #ifndef ANDROID_STATS_LOG_STATS_EVENT_H 18 #define ANDROID_STATS_LOG_STATS_EVENT_H 19 20 #include <stdbool.h> 21 #include <stddef.h> 22 #include <stdint.h> 23 24 /* 25 * Functionality to build and store the buffer sent over the statsd socket. 26 * This code defines and encapsulates the socket protocol. 27 * 28 * Usage: 29 * AStatsEvent* event = AStatsEvent_obtain(); 30 * 31 * AStatsEvent_setAtomId(event, atomId); 32 * AStatsEvent_addBoolAnnotation(event, 5, false); // atom-level annotation 33 * AStatsEvent_writeInt32(event, 24); 34 * AStatsEvent_addBoolAnnotation(event, 1, true); // annotation for preceding atom field 35 * AStatsEvent_addInt32Annotation(event, 2, 128); 36 * AStatsEvent_writeFloat(event, 2.0); 37 * 38 * AStatsEvent_write(event); 39 * AStatsEvent_release(event); 40 * 41 * Note that calls to add atom fields and annotations should be made in the 42 * order that they are defined in the atom. 43 */ 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif // __CPLUSPLUS 48 49 /** 50 * Opaque struct use to represent a StatsEvent. It builds and stores the data that is sent to 51 * statsd. 52 */ 53 struct AStatsEvent; 54 typedef struct AStatsEvent AStatsEvent; 55 56 /** 57 * Returns a new AStatsEvent. If you call this function, you must call AStatsEvent_release to free 58 * the allocated memory. 59 */ 60 AStatsEvent* AStatsEvent_obtain(); 61 62 /** 63 * Builds and finalizes the AStatsEvent for a pulled event. 64 * This should only be called for pulled AStatsEvents. 65 * 66 * After this function, the StatsEvent must not be modified in any way other than calling release or 67 * write. 68 * 69 * Build can be called multiple times without error. 70 * If the event has been built before, this function is a no-op. 71 */ 72 void AStatsEvent_build(AStatsEvent* event); 73 74 /** 75 * Writes the StatsEvent to the stats log. 76 * 77 * After calling this, AStatsEvent_release must be called, 78 * and is the only function that can be safely called. 79 */ 80 int AStatsEvent_write(AStatsEvent* event); 81 82 /** 83 * Frees the memory held by this StatsEvent. 84 * 85 * After calling this, the StatsEvent must not be used or modified in any way. 86 */ 87 void AStatsEvent_release(AStatsEvent* event); 88 89 /** 90 * Sets the atom id for this StatsEvent. 91 * 92 * This function should be called immediately after AStatsEvent_obtain. It may 93 * be called additional times as well, but subsequent calls will have no effect. 94 **/ 95 void AStatsEvent_setAtomId(AStatsEvent* event, uint32_t atomId); 96 97 /** 98 * Writes an int32_t field to this StatsEvent. 99 **/ 100 void AStatsEvent_writeInt32(AStatsEvent* event, int32_t value); 101 102 /** 103 * Writes an int64_t field to this StatsEvent. 104 **/ 105 void AStatsEvent_writeInt64(AStatsEvent* event, int64_t value); 106 107 /** 108 * Writes a float field to this StatsEvent. 109 **/ 110 void AStatsEvent_writeFloat(AStatsEvent* event, float value); 111 112 /** 113 * Write a bool field to this StatsEvent. 114 **/ 115 void AStatsEvent_writeBool(AStatsEvent* event, bool value); 116 117 /** 118 * Write a byte array field to this StatsEvent. 119 **/ 120 void AStatsEvent_writeByteArray(AStatsEvent* event, const uint8_t* buf, size_t numBytes); 121 122 /** 123 * Write a string field to this StatsEvent. 124 * 125 * The string must be null-terminated. 126 **/ 127 void AStatsEvent_writeString(AStatsEvent* event, const char* value); 128 129 /** 130 * Write an attribution chain field to this StatsEvent. 131 * 132 * The sizes of uids and tags must be equal. The AttributionNode at position i is 133 * made up of uids[i] and tags[i]. 134 * 135 * \param uids array of uids in the attribution chain. 136 * \param tags array of tags in the attribution chain. Each tag must be null-terminated. 137 * \param numNodes the number of AttributionNodes in the attribution chain. This is the length of 138 * the uids and the tags. 139 **/ 140 void AStatsEvent_writeAttributionChain(AStatsEvent* event, const uint32_t* uids, 141 const char* const* tags, uint8_t numNodes); 142 143 /** 144 * Write a bool annotation for the previous field written. 145 **/ 146 void AStatsEvent_addBoolAnnotation(AStatsEvent* event, uint8_t annotationId, bool value); 147 148 /** 149 * Write an integer annotation for the previous field written. 150 **/ 151 void AStatsEvent_addInt32Annotation(AStatsEvent* event, uint8_t annotationId, int32_t value); 152 153 // Internal/test APIs. Should not be exposed outside of the APEX. 154 void AStatsEvent_overwriteTimestamp(AStatsEvent* event, uint64_t timestampNs); 155 uint32_t AStatsEvent_getAtomId(AStatsEvent* event); 156 // Size is an output parameter. 157 uint8_t* AStatsEvent_getBuffer(AStatsEvent* event, size_t* size); 158 uint32_t AStatsEvent_getErrors(AStatsEvent* event); 159 160 #ifdef __cplusplus 161 } 162 #endif // __CPLUSPLUS 163 164 #endif // ANDROID_STATS_LOG_STATS_EVENT_H 165