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 `name` to `value`, creating the system property if it doesn't already exist.
45 */
46int __system_property_set(const char* __name, 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 (*__callback)(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, uint32_t __old_serial, uint32_t* __new_serial_ptr, const struct timespec* __relative_timeout)
86    __INTRODUCED_IN(26);
87
88/* Deprecated. In Android O and above, there's no limit on property name length. */
89#define PROP_NAME_MAX   32
90/* Deprecated. Use __system_property_read_callback instead. */
91int __system_property_read(const prop_info* __pi, char* __name, char* __value);
92/* Deprecated. Use __system_property_read_callback instead. */
93int __system_property_get(const char* __name, char* __value);
94/* Deprecated. Use __system_property_foreach instead. */
95const prop_info* __system_property_find_nth(unsigned __n);
96
97__END_DECLS
98
99#endif
100