1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
/** @file
* MS COM / XPCOM Abstraction Layer - COM initialization / shutdown.
*/
/*
* Copyright (C) 2005-2025 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
* in the VirtualBox distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
*/
#ifndef VBOX_INCLUDED_com_utils_h
#define VBOX_INCLUDED_com_utils_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include "iprt/types.h"
/** @addtogroup grp_com
* @{
*/
namespace com
{
/**
* Returns the VirtualBox user home directory.
*
* On failure, this function will return a path that caused a failure (or
* NULL if the failure is not path-related).
*
* On success, this function will try to create the returned directory if it
* doesn't exist yet. This may also fail with the corresponding status code.
*
* If @a aDirLen is smaller than RTPATH_MAX then there is a great chance that
* this method will return VERR_BUFFER_OVERFLOW.
*
* @param aDir Buffer to store the directory string in UTF-8 encoding.
* @param aDirLen Length of the supplied buffer including space for the
* terminating null character, in bytes.
* @param fCreateDir Flag whether to create the returned directory on success
* if it doesn't exist.
* @returns VBox status code.
*/
int GetVBoxUserHomeDirectory(char *aDir, size_t aDirLen, bool fCreateDir = true);
/**
* Creates a release log file, used both in VBoxSVC and in API clients.
*
* @param pszEntity Human readable name of the program.
* @param pszLogFile Name of the release log file.
* @param fFlags Logger instance flags.
* @param pszGroupSettings Group logging settings.
* @param pszEnvVarBase Base environment variable name for the logger.
* @param fDestFlags Logger destination flags.
* @param cMaxEntriesPerGroup Limit for log entries per group. UINT32_MAX for no limit.
* @param cHistory Number of old log files to keep.
* @param uHistoryFileTime Maximum amount of time to put in a log file.
* @param uHistoryFileSize Maximum size of a log file before rotating.
* @param pErrInfo Where to return extended error information.
* Optional.
*
* @returns VBox status code.
*/
int VBoxLogRelCreate(const char *pszEntity, const char *pszLogFile,
uint32_t fFlags, const char *pszGroupSettings,
const char *pszEnvVarBase, uint32_t fDestFlags,
uint32_t cMaxEntriesPerGroup, uint32_t cHistory,
uint32_t uHistoryFileTime, uint64_t uHistoryFileSize,
PRTERRINFO pErrInfo);
/**
* Creates a release log file, used both in VBoxSVC and in API clients.
*
* @param pszEntity Human readable name of the program.
* @param pszLogFile Name of the release log file.
* @param fFlags Logger instance flags.
* @param pszGroupSettings Group logging settings.
* @param pszEnvVarBase Base environment variable name for the logger.
* @param fDestFlags Logger destination flags.
* @param cMaxEntriesPerGroup Limit for log entries per group. UINT32_MAX for no limit.
* @param cHistory Number of old log files to keep.
* @param uHistoryFileTime Maximum amount of time to put in a log file.
* @param uHistoryFileSize Maximum size of a log file before rotating.
* @param pOutputIf The optional file output interface, can be NULL which will
* make use of the default one.
* @param pvOutputIfUser The opaque user data to pass to the callbacks in the output interface.
* @param pErrInfo Where to return extended error information.
* Optional.
*
* @returns VBox status code.
*
* @note Can't include log.h here because of precompiled header fun, hence pOutputIf is void *...
*/
int VBoxLogRelCreateEx(const char *pszEntity, const char *pszLogFile,
uint32_t fFlags, const char *pszGroupSettings,
const char *pszEnvVarBase, uint32_t fDestFlags,
uint32_t cMaxEntriesPerGroup, uint32_t cHistory,
uint32_t uHistoryFileTime, uint64_t uHistoryFileSize,
const void *pOutputIf, void *pvOutputIfUser,
PRTERRINFO pErrInfo);
} /* namespace com */
/** @} */
#endif /* !VBOX_INCLUDED_com_utils_h */
|
