1/*
2 * Copyright (C) 2008 The Android Open Source Project
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *  * Redistributions of source code must retain the above copyright
9 *    notice, this list of conditions and the following disclaimer.
10 *  * Redistributions in binary form must reproduce the above copyright
11 *    notice, this list of conditions and the following disclaimer in
12 *    the documentation and/or other materials provided with the
13 *    distribution.
14 *
15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
18 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
19 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
21 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
22 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
23 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
25 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 * SUCH DAMAGE.
27 */
28
29#ifndef _INCLUDE_SYS_SYSTEM_PROPERTIES_H
30#define _INCLUDE_SYS_SYSTEM_PROPERTIES_H
31
32#include <sys/cdefs.h>
33#include <stdbool.h>
34#include <stddef.h>
35#include <stdint.h>
36
37__BEGIN_DECLS
38
39typedef struct prop_info prop_info;
40
41#define PROP_VALUE_MAX  92
42
43/*
44 * Sets system property `key` to `value`, creating the system property if it doesn't already exist.
45 */
46int __system_property_set(const char* key, const char* value) __INTRODUCED_IN(12);
47
48/*
49 * Returns a `prop_info` corresponding system property `name`, or nullptr if it doesn't exist.
50 * Use __system_property_read_callback to query the current value.
51 *
52 * Property lookup is expensive, so it can be useful to cache the result of this function.
53 */
54const prop_info* __system_property_find(const char* name);
55
56/*
57 * Calls `callback` with a consistent trio of name, value, and serial number for property `pi`.
58 */
59void __system_property_read_callback(const prop_info *pi,
60    void (*callback)(void* cookie, const char *name, const char *value, uint32_t serial),
61    void* cookie) __INTRODUCED_IN(26);
62
63/*
64 * Passes a `prop_info` for each system property to the provided
65 * callback.  Use __system_property_read_callback() to read the value.
66 *
67 * This method is for inspecting and debugging the property system, and not generally useful.
68 */
69int __system_property_foreach(void (*propfn)(const prop_info* pi, void* cookie), void* cookie)
70  __INTRODUCED_IN(19);
71
72/*
73 * Waits for the specific system property identified by `pi` to be updated
74 * past `old_serial`. Waits no longer than `relative_timeout`, or forever
75 * if `relaive_timeout` is null.
76 *
77 * If `pi` is null, waits for the global serial number instead.
78 *
79 * If you don't know the current serial, use 0.
80 *
81 * Returns true and updates `*new_serial_ptr` on success, or false if the call
82 * timed out.
83 */
84struct timespec;
85bool __system_property_wait(const prop_info* pi,
86                            uint32_t old_serial,
87                            uint32_t* new_serial_ptr,
88                            const struct timespec* relative_timeout)
89    __INTRODUCED_IN(26);
90
91/* Deprecated. In Android O and above, there's no limit on property name length. */
92#define PROP_NAME_MAX   32
93/* Deprecated. Use __system_property_read_callback instead. */
94int __system_property_read(const prop_info* pi, char* name, char* value);
95/* Deprecated. Use __system_property_read_callback instead. */
96int __system_property_get(const char* name, char* value);
97/* Deprecated. Use __system_property_foreach instead. */
98const prop_info* __system_property_find_nth(unsigned n);
99
100__END_DECLS
101
102#endif
103