summaryrefslogtreecommitdiffstats
path: root/include/VBox/com/utils.h
blob: 1fd37e7267e855b4ac57bd24b2d28eccb356b193 (plain)
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-2023 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 */