1 /*
2  * Copyright (C) 2023, 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 <stdint.h>
19 #include <sys/cdefs.h>
20 
21 #ifndef __STATSD_SUBS_MIN_API__
22 #define __STATSD_SUBS_MIN_API__ __ANDROID_API_U__
23 #endif
24 
25 __BEGIN_DECLS
26 
27 /**
28  * Reason codes for why subscription callback was triggered.
29  */
30 typedef enum AStatsManager_SubscriptionCallbackReason : uint32_t {
31     /**
32      * SubscriptionCallbackReason constant for subscription data transfer initiated by stats
33      * service.
34      *
35      * Introduced in API 34.
36      */
37     ASTATSMANAGER_SUBSCRIPTION_CALLBACK_REASON_STATSD_INITIATED = 1,
38 
39     /**
40      * SubscriptionCallbackReason constant for subscriber requesting flush of pending data.
41      *
42      * Introduced in API 34.
43      */
44     ASTATSMANAGER_SUBSCRIPTION_CALLBACK_REASON_FLUSH_REQUESTED = 2,
45 
46     /**
47      * SubscriptionCallbackReason constant for final stream of data for a subscription.
48      *
49      * Introduced in API 34.
50      */
51     ASTATSMANAGER_SUBSCRIPTION_CALLBACK_REASON_SUBSCRIPTION_ENDED = 3,
52 } AStatsManager_SubscriptionCallbackReason;
53 
54 /**
55  * Callback interface for receiving subscription data by the stats service.
56  *
57  * This will be called on an arbitrary binder thread. There is a pool of such threads and there is a
58  * no guarantee a single thread will be used even for the same subscription. Clients must ensure it
59  * is safe to call callback from arbitrary threads.
60  *
61  * \param subscription_id the subscription id for which the callback is triggered.
62  * \param reason code for why the callback is triggered.
63  * \param payload encoded SubscriptionResults proto containing subscription data.
64  *        Cannot be null.
65  * \param num_bytes size in bytes of the payload.
66  * \param cookie the opaque pointer passed in AStatsManager_addSubscription. Can be null.
67  *
68  * Introduced in API 34.
69  */
70 typedef void (*AStatsManager_SubscriptionCallback)(int32_t subscription_id,
71                                                    AStatsManager_SubscriptionCallbackReason reason,
72                                                    uint8_t* _Nonnull payload, size_t num_bytes,
73                                                    void* _Nullable cookie);
74 
75 /**
76  * Adds a new subscription.
77  *
78  * Requires caller is in the traced_probes selinux domain.
79  *
80  * \param subscription_config encoded ShellSubscription proto containing parameters for a new
81  *        subscription. Cannot be null.
82  * \param num_bytes size in bytes of the subscription_config.
83  * \param callback function called to deliver subscription data back to the subscriber. Each
84  *        callback can be used for more than one subscription. Cannot be null.
85  * \param cookie opaque pointer to associate with the subscription. The provided callback will be
86  *        invoked with this cookie as an argument when delivering data for this subscription. Can be
87  *        null.
88  * \return subscription ID for the new subscription. Subscription ID is a positive integer. A
89  * negative value indicates an error.
90  *
91  * Introduced in API 34.
92  */
93 int32_t AStatsManager_addSubscription(const uint8_t* _Nonnull subscription_config, size_t num_bytes,
94                                       const AStatsManager_SubscriptionCallback _Nonnull callback,
95                                       void* _Nullable cookie)
96         __INTRODUCED_IN(__STATSD_SUBS_MIN_API__);
97 
98 /**
99  * Removes an existing subscription.
100  * This will trigger a flush of the remaining subscription data through
101  * AStatsManager_SubscriptionCallback with the reason as
102  * ASTATSMANAGER_SUBSCRIPTION_CALLBACK_REASON_SUBSCRIPTION_ENDED.
103  *
104  * Requires caller is in the traced_probes selinux domain.
105  *
106  * \param subscription_id subscription id of the subscription to terminate.
107  *
108  * Introduced in API 34.
109  */
110 void AStatsManager_removeSubscription(int32_t subscription_id)
111         __INTRODUCED_IN(__STATSD_SUBS_MIN_API__);
112 
113 /**
114  * Request stats service to flush a subscription.
115  * This will trigger AStatsManager_SubscriptionCallback with the reason as
116  * ASTATSMANAGER_SUBSCRIPTION_CALLBACK_REASON_FLUSH_REQUESTED.
117  *
118  * Requires caller is in the traced_probes selinux domain.
119  *
120  * \param subscription_id ID of the subscription to be flushed.
121  *
122  * Introduced in API 34.
123  */
124 void AStatsManager_flushSubscription(int32_t subscription_id)
125         __INTRODUCED_IN(__STATSD_SUBS_MIN_API__);
126 
127 __END_DECLS
128