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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
/** @file
* IPRT CD/DVD/BD-ROM Drive API.
*/
/*
* Copyright (C) 2012-2022 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 IPRT_INCLUDED_cdrom_h
#define IPRT_INCLUDED_cdrom_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <iprt/types.h>
RT_C_DECLS_BEGIN
/** @defgroup grp_rt_cdrom IPRT CD/DVD/BD-ROM Drive API
* @ingroup grp_rt
*
* The user of the API is currently resposible for serializing calls to it.
*
* @{
*/
/** CD-ROM drive handle. */
typedef struct RTCDROMINT *RTCDROM;
/** Pointer to a CD-ROM handle. */
typedef RTCDROM *PRTCDROM;
/** NIL CD-ROM handle value. */
#define NIL_RTCDROM ((RTCDROM)0)
/** @name CD-ROM open flags.
* @{ */
#define RTCDROM_O_READ RT_BIT(0)
#define RTCDROM_O_WRITE RT_BIT(1)
#define RTCDROM_O_CONTROL RT_BIT(2)
#define RTCDROM_O_QUERY RT_BIT(3)
#define RTCDROM_O_ALL_ACCESS (RTCDROM_O_READ | RTCDROM_O_WRITE | RTCDROM_O_CONTROL | RTCDROM_O_QUERY)
/** @} */
/**
* Opens the CD-ROM drive (by name).
*
* @returns IPRT status code.
* @param pszName The CD-ROM name (path).
* @param fFlags Open flags, see RTCDROM_O_XXX.
* @param phCdrom Where to return the CDROM handle.
*/
RTDECL(int) RTCdromOpen(const char *pszName, uint32_t fFlags, PRTCDROM phCdrom);
/**
* Retains a reference to the CD-ROM handle.
*
* @returns New reference count, UINT32_MAX on invalid handle (asserted).
* @param hCdrom The CD-ROM handle to retain.
*/
RTDECL(uint32_t) RTCdromRetain(RTCDROM hCdrom);
/**
* Releases a reference to the CD-ROM handle.
*
* When the reference count reaches zero, the CD-ROM handle is destroy.
*
* @returns New reference count, UINT32_MAX on invalid handle (asserted).
* @param hCdrom The CD-ROM handle to retain.
*/
RTDECL(uint32_t) RTCdromRelease(RTCDROM hCdrom);
/**
* Query the primary mount point of the CD-ROM.
*
* @returns IPRT status code.
* @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer will be
* set to an empty string if possible.
*
* @param hCdrom The CD-ROM handle.
* @param pszMountPoint Where to return the mount point.
* @param cbMountPoint The size of the mount point buffer.
*/
RTDECL(int) RTCdromQueryMountPoint(RTCDROM hCdrom, char *pszMountPoint, size_t cbMountPoint);
/**
* Unmounts all file-system mounts related to the CD-ROM.
*
* @returns IPRT status code.
* @param hCdrom The CD-ROM handle.
*/
RTDECL(int) RTCdromUnmount(RTCDROM hCdrom);
/**
* Ejects the CD-ROM from the drive.
*
* @returns IPRT status code.
* @param hCdrom The CD-ROM handle.
* @param fForce If set, unmount and unlock will be performed.
*/
RTDECL(int) RTCdromEject(RTCDROM hCdrom, bool fForce);
/**
* Locks the CD-ROM so it cannot be ejected by the user or system.
*
* @returns IPRT status code.
* @param hCdrom The CD-ROM handle.
*/
RTDECL(int) RTCdromLock(RTCDROM hCdrom);
/**
* Unlocks the CD-ROM so it can be ejected by the user or system.
*
* @returns IPRT status code.
* @param hCdrom The CD-ROM handle.
*/
RTDECL(int) RTCdromUnlock(RTCDROM hCdrom);
/** @name Ordinal / Enumeration
* @{ */
/**
* Get the current number of CD-ROMs.
*
* This is handy for using RTCdromOpenByOrdinal() or RTCdromOrdinalToName() to
* perform some kind of enumeration of all drives.
*
* @returns Number of CD-ROM drivers in the system.
*/
RTDECL(unsigned) RTCdromCount(void);
/**
* Translates an CD-ROM drive ordinal number to a path suitable for RTCdromOpen.
*
* @returns IRPT status code.
* @retval VINF_SUCCESS on success, with the name in the buffer.
* @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer will be
* set to an empty string if possible, in order to prevent trouble.
* @retval VERR_OUT_OF_RANGE if the ordinal number is higher than the current
* number of CD-ROM drives.
*
* @param iCdrom The CD-ROM drive ordinal. Starts at 0.
* @param pszName Where to return the name (path).
* @param cbName Size of the output buffer.
*
* @remarks The ordinals are volatile. They may change as drives are attached
* or detected from the host.
*/
RTDECL(int) RTCdromOrdinalToName(unsigned iCdrom, char *pszName, size_t cbName);
/**
* Combination of RTCdromOrdinalToName() and RTCdromOpen().
*
* @returns IPRT status code.
* @param iCdrom The CD-ROM number.
* @param fFlags Open flags, see RTCDROM_O_XXX.
* @param phCdrom Where to return the CDROM handle .
* @remarks See remarks on RTCdromOrdinalToName().
*/
RTDECL(int) RTCdromOpenByOrdinal(unsigned iCdrom, uint32_t fFlags, PRTCDROM phCdrom);
/** @} */
/** @} */
RT_C_DECLS_END
#endif /* !IPRT_INCLUDED_cdrom_h */
|
