VirtualBox

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

Last change on this file since 94676 was 93115, checked in by vboxsync, 3 years ago

scm --update-copyright-year

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