VirtualBox

source: vbox/trunk/include/iprt/cdrom.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: 6.1 KB
Line 
1/** @file
2 * IPRT CD/DVD/BD-ROM Drive API.
3 */
4
5/*
6 * Copyright (C) 2012-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_cdrom_h
37#define IPRT_INCLUDED_cdrom_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/types.h>
43
44RT_C_DECLS_BEGIN
45
46/** @defgroup grp_rt_cdrom IPRT CD/DVD/BD-ROM Drive API
47 * @ingroup grp_rt
48 *
49 * The user of the API is currently resposible for serializing calls to it.
50 *
51 * @{
52 */
53
54/** CD-ROM drive handle. */
55typedef struct RTCDROMINT *RTCDROM;
56/** Pointer to a CD-ROM handle. */
57typedef RTCDROM *PRTCDROM;
58/** NIL CD-ROM handle value. */
59#define NIL_RTCDROM ((RTCDROM)0)
60
61
62/** @name CD-ROM open flags.
63 * @{ */
64#define RTCDROM_O_READ RT_BIT(0)
65#define RTCDROM_O_WRITE RT_BIT(1)
66#define RTCDROM_O_CONTROL RT_BIT(2)
67#define RTCDROM_O_QUERY RT_BIT(3)
68#define RTCDROM_O_ALL_ACCESS (RTCDROM_O_READ | RTCDROM_O_WRITE | RTCDROM_O_CONTROL | RTCDROM_O_QUERY)
69/** @} */
70
71/**
72 * Opens the CD-ROM drive (by name).
73 *
74 * @returns IPRT status code.
75 * @param pszName The CD-ROM name (path).
76 * @param fFlags Open flags, see RTCDROM_O_XXX.
77 * @param phCdrom Where to return the CDROM handle.
78 */
79RTDECL(int) RTCdromOpen(const char *pszName, uint32_t fFlags, PRTCDROM phCdrom);
80
81/**
82 * Retains a reference to the CD-ROM handle.
83 *
84 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
85 * @param hCdrom The CD-ROM handle to retain.
86 */
87RTDECL(uint32_t) RTCdromRetain(RTCDROM hCdrom);
88
89/**
90 * Releases a reference to the CD-ROM handle.
91 *
92 * When the reference count reaches zero, the CD-ROM handle is destroy.
93 *
94 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
95 * @param hCdrom The CD-ROM handle to retain.
96 */
97RTDECL(uint32_t) RTCdromRelease(RTCDROM hCdrom);
98
99/**
100 * Query the primary mount point of the CD-ROM.
101 *
102 * @returns IPRT status code.
103 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer will be
104 * set to an empty string if possible.
105 *
106 * @param hCdrom The CD-ROM handle.
107 * @param pszMountPoint Where to return the mount point.
108 * @param cbMountPoint The size of the mount point buffer.
109 */
110RTDECL(int) RTCdromQueryMountPoint(RTCDROM hCdrom, char *pszMountPoint, size_t cbMountPoint);
111
112/**
113 * Unmounts all file-system mounts related to the CD-ROM.
114 *
115 * @returns IPRT status code.
116 * @param hCdrom The CD-ROM handle.
117 */
118RTDECL(int) RTCdromUnmount(RTCDROM hCdrom);
119
120/**
121 * Ejects the CD-ROM from the drive.
122 *
123 * @returns IPRT status code.
124 * @param hCdrom The CD-ROM handle.
125 * @param fForce If set, unmount and unlock will be performed.
126 */
127RTDECL(int) RTCdromEject(RTCDROM hCdrom, bool fForce);
128
129/**
130 * Locks the CD-ROM so it cannot be ejected by the user or system.
131 *
132 * @returns IPRT status code.
133 * @param hCdrom The CD-ROM handle.
134 */
135RTDECL(int) RTCdromLock(RTCDROM hCdrom);
136
137/**
138 * Unlocks the CD-ROM so it can be ejected by the user or system.
139 *
140 * @returns IPRT status code.
141 * @param hCdrom The CD-ROM handle.
142 */
143RTDECL(int) RTCdromUnlock(RTCDROM hCdrom);
144
145
146/** @name Ordinal / Enumeration
147 * @{ */
148/**
149 * Get the current number of CD-ROMs.
150 *
151 * This is handy for using RTCdromOpenByOrdinal() or RTCdromOrdinalToName() to
152 * perform some kind of enumeration of all drives.
153 *
154 * @returns Number of CD-ROM drivers in the system.
155 */
156RTDECL(unsigned) RTCdromCount(void);
157
158/**
159 * Translates an CD-ROM drive ordinal number to a path suitable for RTCdromOpen.
160 *
161 * @returns IRPT status code.
162 * @retval VINF_SUCCESS on success, with the name in the buffer.
163 * @retval VERR_BUFFER_OVERFLOW if the buffer is too small. The buffer will be
164 * set to an empty string if possible, in order to prevent trouble.
165 * @retval VERR_OUT_OF_RANGE if the ordinal number is higher than the current
166 * number of CD-ROM drives.
167 *
168 * @param iCdrom The CD-ROM drive ordinal. Starts at 0.
169 * @param pszName Where to return the name (path).
170 * @param cbName Size of the output buffer.
171 *
172 * @remarks The ordinals are volatile. They may change as drives are attached
173 * or detected from the host.
174 */
175RTDECL(int) RTCdromOrdinalToName(unsigned iCdrom, char *pszName, size_t cbName);
176
177/**
178 * Combination of RTCdromOrdinalToName() and RTCdromOpen().
179 *
180 * @returns IPRT status code.
181 * @param iCdrom The CD-ROM number.
182 * @param fFlags Open flags, see RTCDROM_O_XXX.
183 * @param phCdrom Where to return the CDROM handle .
184 * @remarks See remarks on RTCdromOrdinalToName().
185 */
186RTDECL(int) RTCdromOpenByOrdinal(unsigned iCdrom, uint32_t fFlags, PRTCDROM phCdrom);
187
188/** @} */
189
190/** @} */
191
192RT_C_DECLS_END
193
194#endif /* !IPRT_INCLUDED_cdrom_h */
195
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