VirtualBox

source: vbox/trunk/include/iprt/inifile.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.4 KB
Line 
1/* $Id: inifile.h 98103 2023-01-17 14:15:46Z vboxsync $ */
2/** @file
3 * IPRT - INI-file parser.
4 */
5
6/*
7 * Copyright (C) 2017-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * The contents of this file may alternatively be used under the terms
26 * of the Common Development and Distribution License Version 1.0
27 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28 * in the VirtualBox distribution, in which case the provisions of the
29 * CDDL are applicable instead of those of the GPL.
30 *
31 * You may elect to license modified versions of this file under the
32 * terms and conditions of either the GPL or the CDDL or both.
33 *
34 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35 */
36
37#ifndef IPRT_INCLUDED_inifile_h
38#define IPRT_INCLUDED_inifile_h
39#ifndef RT_WITHOUT_PRAGMA_ONCE
40# pragma once
41#endif
42
43
44#include <iprt/types.h>
45
46RT_C_DECLS_BEGIN
47
48/** @defgroup grp_rt_inifile RTIniFile - INI-file parser
49 * @ingroup grp_rt
50 * @{
51 */
52
53/** @name RTINIFILE_F_XXX - INI-file open flags.
54 * @{ */
55/** Readonly. */
56#define RTINIFILE_F_READONLY RT_BIT(0)
57/** Valid mask. */
58#define RTINIFILE_F_VALID_MASK UINT32_C(0x00000001)
59/** @} */
60
61
62
63/**
64 * Creates a INI-file instance from a VFS file handle.
65 *
66 * @returns IPRT status code
67 * @param phIniFile Where to return the INI-file handle.
68 * @param hVfsFile The VFS file handle (not consumed, additional
69 * reference is retained).
70 * @param fFlags Flags, RTINIFILE_F_XXX.
71 */
72RTDECL(int) RTIniFileCreateFromVfsFile(PRTINIFILE phIniFile, RTVFSFILE hVfsFile, uint32_t fFlags);
73
74/**
75 * Retains a reference to an INI-file instance.
76 *
77 * @returns New reference count, UINT32_MAX on failure.
78 * @param hIniFile The INI-file handle.
79 */
80RTDECL(uint32_t) RTIniFileRetain(RTINIFILE hIniFile);
81
82/**
83 * Releases a reference to an INI-file instance, destroying it if the count
84 * reaches zero.
85 *
86 * @returns New reference count, UINT32_MAX on failure.
87 * @param hIniFile The INI-file handle. NIL is ignored.
88 */
89RTDECL(uint32_t) RTIniFileRelease(RTINIFILE hIniFile);
90
91/**
92 * Queries a named value in a section.
93 *
94 * The first matching value is returned. The matching is by default case
95 * insensitive.
96 *
97 * @returns IPRT status code.
98 * @retval VERR_NOT_FOUND if section or key not found.
99 *
100 * @param hIniFile The INI-file handle.
101 * @param pszSection The section name. Pass NULL to refer to the
102 * unsectioned key space at the top of the file.
103 * @param pszKey The key name.
104 * @param pszValue Where to return the value.
105 * @param cbValue Size of the buffer @a pszValue points to.
106 * @param pcbActual Where to return the actual value size excluding
107 * terminator on success. On VERR_BUFFER_OVERFLOW this
108 * will be set to the buffer size needed to hold the
109 * value, terminator included. Optional.
110 */
111RTDECL(int) RTIniFileQueryValue(RTINIFILE hIniFile, const char *pszSection, const char *pszKey,
112 char *pszValue, size_t cbValue, size_t *pcbActual);
113
114/**
115 * Queries a key-value pair in a section by ordinal.
116 *
117 * @returns IPRT status code.
118 * @retval VERR_NOT_FOUND if the section wasn't found or if it contains no pair
119 * with the given ordinal value.
120 *
121 * @param hIniFile The INI-file handle.
122 * @param pszSection The section name. Pass NULL to refer to the
123 * unsectioned key space at the top of the file.
124 * @param idxPair The pair to fetch (counting from 0).
125 *
126 * @param pszKey Where to return the key name.
127 * @param cbKey Size of the buffer @a pszKey points to.
128 * @param pcbKeyActual Where to return the actual key size excluding
129 * terminator on success. On VERR_BUFFER_OVERFLOW this
130 * will be set to the buffer size needed to hold the
131 * value, terminator included. Optional.
132 *
133 * @param pszValue Where to return the value.
134 * @param cbValue Size of the buffer @a pszValue points to.
135 * @param pcbValueActual Where to return the actual value size excluding
136 * terminator on success. On VERR_BUFFER_OVERFLOW this
137 * will be set to the buffer size needed to hold the
138 * value, terminator included. Optional.
139 */
140RTDECL(int) RTIniFileQueryPair(RTINIFILE hIniFile, const char *pszSection, uint32_t idxPair,
141 char *pszKey, size_t cbKey, size_t *pcbKeyActual,
142 char *pszValue, size_t cbValue, size_t *pcbValueActual);
143
144
145/** @} */
146
147RT_C_DECLS_END
148
149#endif /* !IPRT_INCLUDED_inifile_h */
150
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette