/** @file
* IPRT CD/DVD/BD-ROM Drive API.
*/
/*
* Copyright (C) 2012-2015 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* you can redistribute it and/or modify it under the terms of the GNU
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE 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.
*/
#ifndef ___iprt_cdrom_h
#define ___iprt_cdrom_h
#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 *psz, 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 pszName The CD-ROM name (path).
* @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