VirtualBox

source: vbox/trunk/include/iprt/fsisomaker.h@ 99802

Last change on this file since 99802 was 98103, checked in by vboxsync, 2 years ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 34.7 KB
Line 
1/** @file
2 * IPRT - ISO Image Maker.
3 */
4
5/*
6 * Copyright (C) 2017-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_fsisomaker_h
37#define IPRT_INCLUDED_fsisomaker_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44#include <iprt/time.h>
45#include <iprt/fs.h>
46
47
48RT_C_DECLS_BEGIN
49
50/** @defgroup grp_rt_fsisomaker RTFsIsoMaker - ISO Image Maker
51 * @ingroup grp_rt_fs
52 * @{
53 */
54
55
56/** @name RTFSISOMAKER_NAMESPACE_XXX - Namespace selector.
57 * @{
58 */
59#define RTFSISOMAKER_NAMESPACE_ISO_9660 RT_BIT_32(0) /**< The primary ISO-9660 namespace. */
60#define RTFSISOMAKER_NAMESPACE_JOLIET RT_BIT_32(1) /**< The joliet namespace. */
61#define RTFSISOMAKER_NAMESPACE_UDF RT_BIT_32(2) /**< The UDF namespace. */
62#define RTFSISOMAKER_NAMESPACE_HFS RT_BIT_32(3) /**< The HFS namespace */
63#define RTFSISOMAKER_NAMESPACE_ALL UINT32_C(0x0000000f) /**< All namespaces. */
64#define RTFSISOMAKER_NAMESPACE_VALID_MASK UINT32_C(0x0000000f) /**< Valid namespace bits. */
65/** @} */
66
67/** Root directory configuration index. */
68#define RTFSISOMAKER_CFG_IDX_ROOT UINT32_C(0)
69
70
71/**
72 * Creates an ISO maker instance.
73 *
74 * @returns IPRT status code.
75 * @param phIsoMaker Where to return the handle to the new ISO maker.
76 */
77RTDECL(int) RTFsIsoMakerCreate(PRTFSISOMAKER phIsoMaker);
78
79/**
80 * Retains a references to an ISO maker instance.
81 *
82 * @returns New reference count on success, UINT32_MAX if invalid handle.
83 * @param hIsoMaker The ISO maker handle.
84 */
85RTDECL(uint32_t) RTFsIsoMakerRetain(RTFSISOMAKER hIsoMaker);
86
87/**
88 * Releases a references to an ISO maker instance.
89 *
90 * @returns New reference count on success, UINT32_MAX if invalid handle.
91 * @param hIsoMaker The ISO maker handle. NIL is ignored.
92 */
93RTDECL(uint32_t) RTFsIsoMakerRelease(RTFSISOMAKER hIsoMaker);
94
95/**
96 * Sets the ISO-9660 level.
97 *
98 * @returns IPRT status code
99 * @param hIsoMaker The ISO maker handle.
100 * @param uIsoLevel The level, 1-3.
101 */
102RTDECL(int) RTFsIsoMakerSetIso9660Level(RTFSISOMAKER hIsoMaker, uint8_t uIsoLevel);
103
104/**
105 * Gets the ISO-9660 level.
106 *
107 * @returns The level, UINT8_MAX if invalid handle.
108 * @param hIsoMaker The ISO maker handle.
109 */
110RTDECL(uint8_t) RTFsIsoMakerGetIso9660Level(RTFSISOMAKER hIsoMaker);
111
112/**
113 * Sets the joliet level.
114 *
115 * @returns IPRT status code
116 * @param hIsoMaker The ISO maker handle.
117 * @param uJolietLevel The joliet UCS-2 level 1-3, or 0 to disable
118 * joliet.
119 */
120RTDECL(int) RTFsIsoMakerSetJolietUcs2Level(RTFSISOMAKER hIsoMaker, uint8_t uJolietLevel);
121
122/**
123 * Sets the rock ridge support level (on the primary ISO-9660 namespace).
124 *
125 * @returns IPRT status code
126 * @param hIsoMaker The ISO maker handle.
127 * @param uLevel 0 if disabled, 1 to just enable, 2 to enable and
128 * write the ER tag.
129 */
130RTDECL(int) RTFsIsoMakerSetRockRidgeLevel(RTFSISOMAKER hIsoMaker, uint8_t uLevel);
131
132/**
133 * Sets the rock ridge support level on the joliet namespace (experimental).
134 *
135 * @returns IPRT status code
136 * @param hIsoMaker The ISO maker handle.
137 * @param uLevel 0 if disabled, 1 to just enable, 2 to enable and
138 * write the ER tag.
139 */
140RTDECL(int) RTFsIsoMakerSetJolietRockRidgeLevel(RTFSISOMAKER hIsoMaker, uint8_t uLevel);
141
142/**
143 * Gets the rock ridge support level (on the primary ISO-9660 namespace).
144 *
145 * @returns 0 if disabled, 1 just enabled, 2 if enabled with ER tag, and
146 * UINT8_MAX if the handle is invalid.
147 * @param hIsoMaker The ISO maker handle.
148 */
149RTDECL(uint8_t) RTFsIsoMakerGetRockRidgeLevel(RTFSISOMAKER hIsoMaker);
150
151/**
152 * Gets the rock ridge support level on the joliet namespace (experimental).
153 *
154 * @returns 0 if disabled, 1 just enabled, 2 if enabled with ER tag, and
155 * UINT8_MAX if the handle is invalid.
156 * @param hIsoMaker The ISO maker handle.
157 */
158RTDECL(uint8_t) RTFsIsoMakerGetJolietRockRidgeLevel(RTFSISOMAKER hIsoMaker);
159
160/**
161 * Changes the file attribute (mode, owner, group) inherit style (from source).
162 *
163 * The strict style will use the exact attributes from the source, where as the
164 * non-strict (aka rational and default) style will use 0 for the owner and
165 * group IDs and normalize the mode bits along the lines of 'chmod a=rX',
166 * stripping set-uid/gid bitson files but preserving sticky ones on directories.
167 *
168 * When disabling strict style, the default dir and file modes will be restored
169 * to default values.
170 *
171 * @returns IRPT status code.
172 * @param hIsoMaker The ISO maker handle.
173 * @param fStrict Indicates strict (true) or non-strict (false)
174 * style.
175 */
176RTDECL(int) RTFsIsoMakerSetAttribInheritStyle(RTFSISOMAKER hIsoMaker, bool fStrict);
177
178/**
179 * Sets the default file mode settings.
180 *
181 * @returns IRPT status code.
182 * @param hIsoMaker The ISO maker handle.
183 * @param fMode The default file mode.
184 */
185RTDECL(int) RTFsIsoMakerSetDefaultFileMode(RTFSISOMAKER hIsoMaker, RTFMODE fMode);
186
187/**
188 * Sets the default dir mode settings.
189 *
190 * @returns IRPT status code.
191 * @param hIsoMaker The ISO maker handle.
192 * @param fMode The default dir mode.
193 */
194RTDECL(int) RTFsIsoMakerSetDefaultDirMode(RTFSISOMAKER hIsoMaker, RTFMODE fMode);
195
196/**
197 * Sets the forced file mode, if @a fForce is true also the default mode is set.
198 *
199 * @returns IRPT status code.
200 * @param hIsoMaker The ISO maker handle.
201 * @param fMode The file mode.
202 * @param fForce Indicate whether forced mode is active or not.
203 */
204RTDECL(int) RTFsIsoMakerSetForcedFileMode(RTFSISOMAKER hIsoMaker, RTFMODE fMode, bool fForce);
205
206/**
207 * Sets the forced dir mode, if @a fForce is true also the default mode is set.
208 *
209 * @returns IRPT status code.
210 * @param hIsoMaker The ISO maker handle.
211 * @param fMode The dir mode.
212 * @param fForce Indicate whether forced mode is active or not.
213 */
214RTDECL(int) RTFsIsoMakerSetForcedDirMode(RTFSISOMAKER hIsoMaker, RTFMODE fMode, bool fForce);
215
216/**
217 * Sets the content of the system area, i.e. the first 32KB of the image.
218 *
219 * This can be used to put generic boot related stuff.
220 *
221 * @note Other settings may overwrite parts of the content (yet to be
222 * determined which).
223 *
224 * @returns IPRT status code
225 * @param hIsoMaker The ISO maker handle.
226 * @param pvContent The content to put in the system area.
227 * @param cbContent The size of the content.
228 * @param off The offset into the system area.
229 */
230RTDECL(int) RTFsIsoMakerSetSysAreaContent(RTFSISOMAKER hIsoMaker, void const *pvContent, size_t cbContent, uint32_t off);
231
232/**
233 * String properties settable thru RTFsIsoMakerSetStringProp.
234 */
235typedef enum RTFSISOMAKERSTRINGPROP
236{
237 /** The customary invalid zero value. */
238 RTFSISOMAKERSTRINGPROP_INVALID = 0,
239 /** The system identifier. */
240 RTFSISOMAKERSTRINGPROP_SYSTEM_ID,
241 /** The volume identifier(label). */
242 RTFSISOMAKERSTRINGPROP_VOLUME_ID,
243 /** The volume set identifier. */
244 RTFSISOMAKERSTRINGPROP_VOLUME_SET_ID,
245 /** The publisher ID (root file reference if it starts with '_'). */
246 RTFSISOMAKERSTRINGPROP_PUBLISHER_ID,
247 /** The data preparer ID (root file reference if it starts with '_'). */
248 RTFSISOMAKERSTRINGPROP_DATA_PREPARER_ID,
249 /** The application ID (root file reference if it starts with '_'). */
250 RTFSISOMAKERSTRINGPROP_APPLICATION_ID,
251 /** The copyright file ID. */
252 RTFSISOMAKERSTRINGPROP_COPYRIGHT_FILE_ID,
253 /** The abstract file ID. */
254 RTFSISOMAKERSTRINGPROP_ABSTRACT_FILE_ID,
255 /** The bibliographic file ID. */
256 RTFSISOMAKERSTRINGPROP_BIBLIOGRAPHIC_FILE_ID,
257 /** End of valid string property values. */
258 RTFSISOMAKERSTRINGPROP_END,
259 /** Make sure it's a 32-bit type. */
260 RTFSISOMAKERSTRINGPROP_32BIT_HACK = 0x7fffffff
261} RTFSISOMAKERSTRINGPROP;
262
263/**
264 * Sets a string property in one or more namespaces.
265 *
266 * @returns IPRT status code.
267 * @param hIsoMaker The ISO maker handle.
268 * @param enmStringProp The string property to set.
269 * @param fNamespaces The namespaces to set it in.
270 * @param pszValue The value to set it to. NULL is treated like an
271 * empty string. The value will be silently truncated
272 * to fit the available space.
273 */
274RTDECL(int) RTFsIsoMakerSetStringProp(RTFSISOMAKER hIsoMaker, RTFSISOMAKERSTRINGPROP enmStringProp,
275 uint32_t fNamespaces, const char *pszValue);
276
277/**
278 * Specifies image padding.
279 *
280 * @returns IPRT status code.
281 * @param hIsoMaker The ISO maker handle.
282 * @param cSectors Number of sectors to pad the image with.
283 */
284RTDECL(int) RTFsIsoMakerSetImagePadding(RTFSISOMAKER hIsoMaker, uint32_t cSectors);
285
286/**
287 * Gets currently populated namespaces.
288 *
289 * @returns Set of namespaces (RTFSISOMAKER_NAMESPACE_XXX), UINT32_MAX on error.
290 * @param hIsoMaker The ISO maker handle.
291 */
292RTDECL(uint32_t) RTFsIsoMakerGetPopulatedNamespaces(RTFSISOMAKER hIsoMaker);
293
294/**
295 * Resolves a path into a object ID.
296 *
297 * This will be doing the looking up using the specified object names rather
298 * than the version adjusted and mangled according to the namespace setup.
299 *
300 * @returns The object ID corresponding to @a pszPath, or UINT32_MAX if not
301 * found or invalid parameters.
302 * @param hIsoMaker The ISO maker instance.
303 * @param fNamespaces The namespace to resolve @a pszPath in. It's
304 * possible to specify multiple namespaces here, of
305 * course, but that's inefficient.
306 * @param pszPath The path to the object.
307 */
308RTDECL(uint32_t) RTFsIsoMakerGetObjIdxForPath(RTFSISOMAKER hIsoMaker, uint32_t fNamespaces, const char *pszPath);
309
310/**
311 * Queries the configuration index of the boot catalog file object.
312 *
313 * The boot catalog file is created as necessary, thus this have to be a query
314 * rather than a getter since object creation may fail.
315 *
316 * @returns IPRT status code.
317 * @param hIsoMaker The ISO maker handle.
318 * @param pidxObj Where to return the configuration index.
319 */
320RTDECL(int) RTFsIsoMakerQueryObjIdxForBootCatalog(RTFSISOMAKER hIsoMaker, uint32_t *pidxObj);
321
322/**
323 * Removes the specified object from the image.
324 *
325 * @returns IPRT status code.
326 * @param hIsoMaker The ISO maker instance.
327 * @param idxObj The index of the object to remove.
328 */
329RTDECL(int) RTFsIsoMakerObjRemove(RTFSISOMAKER hIsoMaker, uint32_t idxObj);
330
331/**
332 * Sets the path (name) of an object in the selected namespaces.
333 *
334 * The name will be transformed as necessary.
335 *
336 * The initial implementation does not allow this function to be called more
337 * than once on an object.
338 *
339 * @returns IPRT status code.
340 * @param hIsoMaker The ISO maker handle.
341 * @param idxObj The configuration index of to name.
342 * @param fNamespaces The namespaces to apply the path to
343 * (RTFSISOMAKER_NAMESPACE_XXX).
344 * @param pszPath The path.
345 */
346RTDECL(int) RTFsIsoMakerObjSetPath(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint32_t fNamespaces, const char *pszPath);
347
348/**
349 * Sets the name of an object in the selected namespaces, placing it under the
350 * given directory.
351 *
352 * The name will be transformed as necessary.
353 *
354 * @returns IPRT status code.
355 * @param hIsoMaker The ISO maker handle.
356 * @param idxObj The configuration index of to name.
357 * @param idxParentObj The parent directory object.
358 * @param fNamespaces The namespaces to apply the path to
359 * (RTFSISOMAKER_NAMESPACE_XXX).
360 * @param pszName The name.
361 * @param fNoNormalize Don't normalize the name (imported or such).
362 */
363RTDECL(int) RTFsIsoMakerObjSetNameAndParent(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint32_t idxParentObj,
364 uint32_t fNamespaces, const char *pszName, bool fNoNormalize);
365
366/**
367 * Changes the rock ridge name for the object in the selected namespaces.
368 *
369 * The object must already be enetered into the namespaces by
370 * RTFsIsoMakerObjSetNameAndParent, RTFsIsoMakerObjSetPath or similar.
371 *
372 * @returns IPRT status code.
373 * @param hIsoMaker The ISO maker handle.
374 * @param idxObj The configuration index of to name.
375 * @param fNamespaces The namespaces to apply the path to
376 * (RTFSISOMAKER_NAMESPACE_XXX).
377 * @param pszRockName The rock ridge name. Passing NULL or an empty
378 * string will restore the specified name.
379 */
380RTDECL(int) RTFsIsoMakerObjSetRockName(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint32_t fNamespaces, const char *pszRockName);
381
382/**
383 * Enables or disable syslinux boot info table patching of a file.
384 *
385 * @returns IPRT status code.
386 * @param hIsoMaker The ISO maker handle.
387 * @param idxObj The configuration index.
388 * @param fEnable Whether to enable or disable patching.
389 */
390RTDECL(int) RTFsIsoMakerObjEnableBootInfoTablePatching(RTFSISOMAKER hIsoMaker, uint32_t idxObj, bool fEnable);
391
392/**
393 * Gets the data size of an object.
394 *
395 * Currently only supported on file objects.
396 *
397 * @returns IPRT status code.
398 * @param hIsoMaker The ISO maker handle.
399 * @param idxObj The configuration index.
400 * @param pcbData Where to return the size.
401 */
402RTDECL(int) RTFsIsoMakerObjQueryDataSize(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint64_t *pcbData);
403
404/**
405 * Adds an unnamed directory to the image.
406 *
407 * The directory must explictly be entered into the desired namespaces.
408 *
409 * @returns IPRT status code
410 * @param hIsoMaker The ISO maker handle.
411 * @param pObjInfo Pointer to object attributes, must be set to
412 * UNIX. The size and hardlink counts are ignored.
413 * Optional.
414 * @param pidxObj Where to return the configuration index of the
415 * directory.
416 * @sa RTFsIsoMakerAddDir, RTFsIsoMakerObjSetPath
417 */
418RTDECL(int) RTFsIsoMakerAddUnnamedDir(RTFSISOMAKER hIsoMaker, PCRTFSOBJINFO pObjInfo, uint32_t *pidxObj);
419
420/**
421 * Adds a directory to the image in all namespaces and default attributes.
422 *
423 * @returns IPRT status code
424 * @param hIsoMaker The ISO maker handle.
425 * @param pszDir The path (UTF-8) to the directory in the ISO.
426 *
427 * @param pidxObj Where to return the configuration index of the
428 * directory. Optional.
429 * @sa RTFsIsoMakerAddUnnamedDir, RTFsIsoMakerObjSetPath
430 */
431RTDECL(int) RTFsIsoMakerAddDir(RTFSISOMAKER hIsoMaker, const char *pszDir, uint32_t *pidxObj);
432
433/**
434 * Adds an unnamed file to the image that's backed by a host file.
435 *
436 * The file must explictly be entered into the desired namespaces.
437 *
438 * @returns IPRT status code
439 * @param hIsoMaker The ISO maker handle.
440 * @param pszSrcFile The source file path. VFS chain spec allowed.
441 * @param pidxObj Where to return the configuration index of the
442 * directory.
443 * @sa RTFsIsoMakerAddFile, RTFsIsoMakerObjSetPath
444 */
445RTDECL(int) RTFsIsoMakerAddUnnamedFileWithSrcPath(RTFSISOMAKER hIsoMaker, const char *pszSrcFile, uint32_t *pidxObj);
446
447/**
448 * Adds an unnamed file to the image that's backed by a VFS file.
449 *
450 * The file must explictly be entered into the desired namespaces.
451 *
452 * @returns IPRT status code
453 * @param hIsoMaker The ISO maker handle.
454 * @param hVfsFileSrc The source file handle.
455 * @param pidxObj Where to return the configuration index of the
456 * directory.
457 * @sa RTFsIsoMakerAddUnnamedFileWithSrcPath, RTFsIsoMakerObjSetPath
458 */
459RTDECL(int) RTFsIsoMakerAddUnnamedFileWithVfsFile(RTFSISOMAKER hIsoMaker, RTVFSFILE hVfsFileSrc, uint32_t *pidxObj);
460
461/**
462 * Adds an unnamed file to the image that's backed by a portion of a common
463 * source file.
464 *
465 * The file must explictly be entered into the desired namespaces.
466 *
467 * @returns IPRT status code
468 * @param hIsoMaker The ISO maker handle.
469 * @param idxCommonSrc The common source file index.
470 * @param offData The offset of the data in the source file.
471 * @param cbData The file size.
472 * @param pObjInfo Pointer to file info. Optional.
473 * @param pidxObj Where to return the configuration index of the
474 * directory.
475 * @sa RTFsIsoMakerAddUnnamedFileWithSrcPath, RTFsIsoMakerObjSetPath
476 */
477RTDECL(int) RTFsIsoMakerAddUnnamedFileWithCommonSrc(RTFSISOMAKER hIsoMaker, uint32_t idxCommonSrc,
478 uint64_t offData, uint64_t cbData, PCRTFSOBJINFO pObjInfo, uint32_t *pidxObj);
479
480/**
481 * Adds a common source file.
482 *
483 * Using RTFsIsoMakerAddUnnamedFileWithCommonSrc a sections common source file
484 * can be referenced to make up other files. The typical use case is when
485 * importing data from an existing ISO.
486 *
487 * @returns IPRT status code
488 * @param hIsoMaker The ISO maker handle.
489 * @param hVfsFile VFS handle of the common source. (A reference
490 * is added, none consumed.)
491 * @param pidxCommonSrc Where to return the assigned common source
492 * index. This is used to reference the file.
493 * @sa RTFsIsoMakerAddUnnamedFileWithCommonSrc
494 */
495RTDECL(int) RTFsIsoMakerAddCommonSourceFile(RTFSISOMAKER hIsoMaker, RTVFSFILE hVfsFile, uint32_t *pidxCommonSrc);
496
497/**
498 * Adds a file that's backed by a host file to the image in all namespaces and
499 * with attributes taken from the source file.
500 *
501 * @returns IPRT status code
502 * @param hIsoMaker The ISO maker handle.
503 * @param pszFile The path to the file in the image.
504 * @param pszSrcFile The source file path. VFS chain spec allowed.
505 * @param pidxObj Where to return the configuration index of the file.
506 * Optional
507 * @sa RTFsIsoMakerAddFileWithVfsFile,
508 * RTFsIsoMakerAddUnnamedFileWithSrcPath
509 */
510RTDECL(int) RTFsIsoMakerAddFileWithSrcPath(RTFSISOMAKER hIsoMaker, const char *pszFile, const char *pszSrcFile, uint32_t *pidxObj);
511
512/**
513 * Adds a file that's backed by a VFS file to the image in all namespaces and
514 * with attributes taken from the source file.
515 *
516 * @returns IPRT status code
517 * @param hIsoMaker The ISO maker handle.
518 * @param pszFile The path to the file in the image.
519 * @param hVfsFileSrc The source file handle.
520 * @param pidxObj Where to return the configuration index of the file.
521 * Optional.
522 * @sa RTFsIsoMakerAddUnnamedFileWithVfsFile,
523 * RTFsIsoMakerAddFileWithSrcPath
524 */
525RTDECL(int) RTFsIsoMakerAddFileWithVfsFile(RTFSISOMAKER hIsoMaker, const char *pszFile, RTVFSFILE hVfsFileSrc, uint32_t *pidxObj);
526
527/**
528 * Adds an unnamed symbolic link to the image.
529 *
530 * The symlink must explictly be entered into the desired namespaces. Please
531 * note that it is not possible to enter a symbolic link into an ISO 9660
532 * namespace where rock ridge extensions are disabled, since symbolic links
533 * depend on rock ridge. For HFS and UDF there is no such requirement.
534 *
535 * Will fail if no namespace is configured that supports symlinks.
536 *
537 * @returns IPRT status code
538 * @retval VERR_ISOMK_SYMLINK_SUPPORT_DISABLED if not supported.
539 * @param hIsoMaker The ISO maker handle.
540 * @param pObjInfo Pointer to object attributes, must be set to
541 * UNIX. The size and hardlink counts are ignored.
542 * Optional.
543 * @param pszTarget The symbolic link target (UTF-8).
544 * @param pidxObj Where to return the configuration index of the
545 * directory.
546 * @sa RTFsIsoMakerAddSymlink, RTFsIsoMakerObjSetPath
547 */
548RTDECL(int) RTFsIsoMakerAddUnnamedSymlink(RTFSISOMAKER hIsoMaker, PCRTFSOBJINFO pObjInfo, const char *pszTarget, uint32_t *pidxObj);
549
550/**
551 * Adds a directory to the image in all namespaces and default attributes.
552 *
553 * Will fail if no namespace is configured that supports symlinks.
554 *
555 * @returns IPRT status code
556 * @param hIsoMaker The ISO maker handle.
557 * @param pszSymlink The path (UTF-8) to the symlink in the ISO.
558 * @param pszTarget The symlink target (UTF-8).
559 * @param pidxObj Where to return the configuration index of the
560 * directory. Optional.
561 * @sa RTFsIsoMakerAddUnnamedSymlink, RTFsIsoMakerObjSetPath
562 */
563RTDECL(int) RTFsIsoMakerAddSymlink(RTFSISOMAKER hIsoMaker, const char *pszSymlink, const char *pszTarget, uint32_t *pidxObj);
564
565/**
566 * Modifies the mode mask for a given path in one or more namespaces.
567 *
568 * The mode mask is used by rock ridge, UDF and HFS.
569 *
570 * @returns IPRT status code.
571 * @retval VWRN_NOT_FOUND if the path wasn't found in any of the specified
572 * namespaces.
573 *
574 * @param hIsoMaker The ISO maker handler.
575 * @param pszPath The path which mode mask should be modified.
576 * @param fNamespaces The namespaces to set it in.
577 * @param fSet The mode bits to set.
578 * @param fUnset The mode bits to clear (applied first).
579 * @param fFlags Reserved, MBZ.
580 * @param pcHits Where to return number of paths found. Optional.
581 */
582RTDECL(int) RTFsIsoMakerSetPathMode(RTFSISOMAKER hIsoMaker, const char *pszPath, uint32_t fNamespaces,
583 RTFMODE fSet, RTFMODE fUnset, uint32_t fFlags, uint32_t *pcHits);
584
585/**
586 * Modifies the owner ID for a given path in one or more namespaces.
587 *
588 * The owner ID is used by rock ridge, UDF and HFS.
589 *
590 * @returns IPRT status code.
591 * @retval VWRN_NOT_FOUND if the path wasn't found in any of the specified
592 * namespaces.
593 *
594 * @param hIsoMaker The ISO maker handler.
595 * @param pszPath The path which mode mask should be modified.
596 * @param fNamespaces The namespaces to set it in.
597 * @param idOwner The new owner ID to set.
598 * @param pcHits Where to return number of paths found. Optional.
599 */
600RTDECL(int) RTFsIsoMakerSetPathOwnerId(RTFSISOMAKER hIsoMaker, const char *pszPath, uint32_t fNamespaces,
601 RTUID idOwner, uint32_t *pcHits);
602
603/**
604 * Modifies the group ID for a given path in one or more namespaces.
605 *
606 * The group ID is used by rock ridge, UDF and HFS.
607 *
608 * @returns IPRT status code.
609 * @retval VWRN_NOT_FOUND if the path wasn't found in any of the specified
610 * namespaces.
611 *
612 * @param hIsoMaker The ISO maker handler.
613 * @param pszPath The path which mode mask should be modified.
614 * @param fNamespaces The namespaces to set it in.
615 * @param idGroup The new group ID to set.
616 * @param pcHits Where to return number of paths found. Optional.
617 */
618RTDECL(int) RTFsIsoMakerSetPathGroupId(RTFSISOMAKER hIsoMaker, const char *pszPath, uint32_t fNamespaces,
619 RTGID idGroup, uint32_t *pcHits);
620
621/**
622 * Set the validation entry of the boot catalog (this is the first entry).
623 *
624 * @returns IPRT status code.
625 * @param hIsoMaker The ISO maker handle.
626 * @param idPlatform The platform ID
627 * (ISO9660_ELTORITO_PLATFORM_ID_XXX).
628 * @param pszString CD/DVD-ROM identifier. Optional.
629 */
630RTDECL(int) RTFsIsoMakerBootCatSetValidationEntry(RTFSISOMAKER hIsoMaker, uint8_t idPlatform, const char *pszString);
631
632/**
633 * Set the validation entry of the boot catalog (this is the first entry).
634 *
635 * @returns IPRT status code.
636 * @param hIsoMaker The ISO maker handle.
637 * @param idxBootCat The boot catalog entry. Zero and two are
638 * invalid. Must be less than 63.
639 * @param idxImageObj The configuration index of the boot image.
640 * @param bBootMediaType The media type and flag (not for entry 1)
641 * (ISO9660_ELTORITO_BOOT_MEDIA_TYPE_XXX,
642 * ISO9660_ELTORITO_BOOT_MEDIA_F_XXX).
643 * @param bSystemType The partitiona table system ID.
644 * @param fBootable Whether it's a bootable entry or if we just want
645 * the BIOS to setup the emulation without booting
646 * it.
647 * @param uLoadSeg The load address divided by 0x10 (i.e. the real
648 * mode segment number).
649 * @param cSectorsToLoad Number of emulated sectors to load.
650 * @param bSelCritType The selection criteria type, if none pass
651 * ISO9660_ELTORITO_SEL_CRIT_TYPE_NONE.
652 * @param pvSelCritData Pointer to the selection criteria data.
653 * @param cbSelCritData Size of the selection criteria data.
654 */
655RTDECL(int) RTFsIsoMakerBootCatSetSectionEntry(RTFSISOMAKER hIsoMaker, uint32_t idxBootCat, uint32_t idxImageObj,
656 uint8_t bBootMediaType, uint8_t bSystemType, bool fBootable,
657 uint16_t uLoadSeg, uint16_t cSectorsToLoad,
658 uint8_t bSelCritType, void const *pvSelCritData, size_t cbSelCritData);
659
660/**
661 * Set the validation entry of the boot catalog (this is the first entry).
662 *
663 * @returns IPRT status code.
664 * @param hIsoMaker The ISO maker handle.
665 * @param idxBootCat The boot catalog entry.
666 * @param cEntries Number of entries in the section.
667 * @param idPlatform The platform ID
668 * (ISO9660_ELTORITO_PLATFORM_ID_XXX).
669 * @param pszString Section identifier or something. Optional.
670 */
671RTDECL(int) RTFsIsoMakerBootCatSetSectionHeaderEntry(RTFSISOMAKER hIsoMaker, uint32_t idxBootCat, uint32_t cEntries,
672 uint8_t idPlatform, const char *pszString);
673
674/**
675 * Sets the boot catalog backing file.
676 *
677 * The content of the given file will be discarded and replaced with the boot
678 * catalog, the naming and file attributes (other than size) will be retained.
679 *
680 * This API exists mainly to assist when importing ISOs.
681 *
682 * @returns IPRT status code.
683 * @param hIsoMaker The ISO maker handle.
684 * @param idxObj The configuration index of the file.
685 */
686RTDECL(int) RTFsIsoMakerBootCatSetFile(RTFSISOMAKER hIsoMaker, uint32_t idxObj);
687
688
689/**
690 * ISO maker import results (RTFsIsoMakerImport).
691 */
692typedef struct RTFSISOMAKERIMPORTRESULTS
693{
694 /** Number of names added. */
695 uint32_t cAddedNames;
696 /** Number of directories added. */
697 uint32_t cAddedDirs;
698 /** Amount of added data blocks, files only. */
699 uint64_t cbAddedDataBlocks;
700 /** Number of unique files added (unique in terms of data location). */
701 uint32_t cAddedFiles;
702 /** Number of symbolic links added. */
703 uint32_t cAddedSymlinks;
704 /** Number of imported boot catalog entries. */
705 uint32_t cBootCatEntries;
706 /** Number of system area bytes imported (from offset zero). */
707 uint32_t cbSysArea;
708
709 /** Number of import errors. */
710 uint32_t cErrors;
711} RTFSISOMAKERIMPORTRESULTS;
712/** Pointer to ISO maker import results. */
713typedef RTFSISOMAKERIMPORTRESULTS *PRTFSISOMAKERIMPORTRESULTS;
714
715/**
716 * Imports an existing ISO.
717 *
718 * Just like other source files, the existing image must remain present and
719 * unmodified till the ISO maker is done with it.
720 *
721 * @returns IRPT status code.
722 * @param hIsoMaker The ISO maker handle.
723 * @param hIsoFile VFS file handle to the existing image to import / clone.
724 * @param fFlags Reserved for the future, MBZ.
725 * @param pResults Where to return import results.
726 * @param pErrInfo Where to return additional error information.
727 * Optional.
728 */
729RTDECL(int) RTFsIsoMakerImport(RTFSISOMAKER hIsoMaker, RTVFSFILE hIsoFile, uint32_t fFlags,
730 PRTFSISOMAKERIMPORTRESULTS pResults, PRTERRINFO pErrInfo);
731
732/** @name RTFSISOMK_IMPORT_F_XXX - Flags for RTFsIsoMakerImport.
733 * @{ */
734#define RTFSISOMK_IMPORT_F_NO_PRIMARY_ISO RT_BIT_32(0) /**< Skip the primary ISO-9660 namespace (rock ridge included). */
735#define RTFSISOMK_IMPORT_F_NO_JOLIET RT_BIT_32(1) /**< Skip the joliet namespace. */
736#define RTFSISOMK_IMPORT_F_NO_ROCK_RIDGE RT_BIT_32(2) /**< Skip rock ridge (both primary and joliet). */
737#define RTFSISOMK_IMPORT_F_NO_UDF RT_BIT_32(3) /**< Skip the UDF namespace. */
738#define RTFSISOMK_IMPORT_F_NO_HFS RT_BIT_32(4) /**< Skip the HFS namespace. */
739#define RTFSISOMK_IMPORT_F_NO_BOOT RT_BIT_32(5) /**< Skip importing El Torito boot stuff. */
740#define RTFSISOMK_IMPORT_F_NO_SYS_AREA RT_BIT_32(6) /**< Skip importing the system area (first 32KB). */
741
742#define RTFSISOMK_IMPORT_F_NO_SYSTEM_ID RT_BIT_32(7) /**< Don't import the system ID primary descriptor field. */
743#define RTFSISOMK_IMPORT_F_NO_VOLUME_ID RT_BIT_32(8) /**< Don't import the volume ID primary descriptor field. */
744#define RTFSISOMK_IMPORT_F_NO_VOLUME_SET_ID RT_BIT_32(9) /**< Don't import the volume set ID primary descriptor field. */
745#define RTFSISOMK_IMPORT_F_NO_PUBLISHER_ID RT_BIT_32(10) /**< Don't import the publisher ID primary descriptor field. */
746#define RTFSISOMK_IMPORT_F_DATA_PREPARER_ID RT_BIT_32(11) /**< Do import the data preparer ID primary descriptor field. */
747#define RTFSISOMK_IMPORT_F_APPLICATION_ID RT_BIT_32(12) /**< Do import the application ID primary descriptor field. */
748#define RTFSISOMK_IMPORT_F_NO_COPYRIGHT_FID RT_BIT_32(13) /**< Don't import the copyright file ID primary descriptor field. */
749#define RTFSISOMK_IMPORT_F_NO_ABSTRACT_FID RT_BIT_32(14) /**< Don't import the abstract file ID primary descriptor field. */
750#define RTFSISOMK_IMPORT_F_NO_BIBLIO_FID RT_BIT_32(15) /**< Don't import the bibliographic file ID primary descriptor field. */
751
752#define RTFSISOMK_IMPORT_F_NO_J_SYSTEM_ID RT_BIT_32(16) /**< Don't import the system ID joliet descriptor field. */
753#define RTFSISOMK_IMPORT_F_NO_J_VOLUME_ID RT_BIT_32(17) /**< Don't import the volume ID joliet descriptor field. */
754#define RTFSISOMK_IMPORT_F_NO_J_VOLUME_SET_ID RT_BIT_32(18) /**< Don't import the volume set ID joliet descriptor field. */
755#define RTFSISOMK_IMPORT_F_NO_J_PUBLISHER_ID RT_BIT_32(19) /**< Don't import the publisher ID joliet descriptor field. */
756#define RTFSISOMK_IMPORT_F_J_DATA_PREPARER_ID RT_BIT_32(20) /**< Do import the data preparer ID joliet descriptor field. */
757#define RTFSISOMK_IMPORT_F_J_APPLICATION_ID RT_BIT_32(21) /**< Do import the application ID joliet descriptor field. */
758#define RTFSISOMK_IMPORT_F_NO_J_COPYRIGHT_FID RT_BIT_32(22) /**< Don't import the copyright file ID joliet descriptor field. */
759#define RTFSISOMK_IMPORT_F_NO_J_ABSTRACT_FID RT_BIT_32(23) /**< Don't import the abstract file ID joliet descriptor field. */
760#define RTFSISOMK_IMPORT_F_NO_J_BIBLIO_FID RT_BIT_32(24) /**< Don't import the bibliographic file ID joliet descriptor field. */
761
762#define RTFSISOMK_IMPORT_F_VALID_MASK UINT32_C(0x01ffffff)
763/** @} */
764
765
766/**
767 * Finalizes the image.
768 *
769 * @returns IPRT status code.
770 * @param hIsoMaker The ISO maker handle.
771 */
772RTDECL(int) RTFsIsoMakerFinalize(RTFSISOMAKER hIsoMaker);
773
774/**
775 * Creates a VFS file for a finalized ISO maker instanced.
776 *
777 * The file can be used to access the image. Both sequential and random access
778 * are supported, so that this could in theory be hooked up to a CD/DVD-ROM
779 * drive emulation and used as a virtual ISO image.
780 *
781 * @returns IRPT status code.
782 * @param hIsoMaker The ISO maker handle.
783 * @param phVfsFile Where to return the handle.
784 */
785RTDECL(int) RTFsIsoMakerCreateVfsOutputFile(RTFSISOMAKER hIsoMaker, PRTVFSFILE phVfsFile);
786
787
788
789/**
790 * ISO maker command (creates image file on disk).
791 *
792 * @returns IPRT status code
793 * @param cArgs Number of arguments.
794 * @param papszArgs Pointer to argument array.
795 */
796RTDECL(RTEXITCODE) RTFsIsoMakerCmd(unsigned cArgs, char **papszArgs);
797
798/**
799 * Extended ISO maker command.
800 *
801 * This can be used as a ISO maker command that produces a image file, or
802 * alternatively for setting up a virtual ISO in memory.
803 *
804 * @returns IPRT status code
805 * @param cArgs Number of arguments.
806 * @param papszArgs Pointer to argument array.
807 * @param hVfsCwd The current working directory to assume when processing
808 * relative file/dir references. Pass NIL_RTVFSDIR to use
809 * the current CWD of the process.
810 * @param pszCwd Path to @a hVfsCwdDir. Use for error reporting and
811 * optimizing the open file count if possible.
812 * @param phVfsFile Where to return the virtual ISO. Pass NULL to for
813 * normal operation (creates file on disk).
814 * @param pErrInfo Where to return extended error information in the
815 * virtual ISO mode.
816 */
817RTDECL(int) RTFsIsoMakerCmdEx(unsigned cArgs, char **papszArgs, RTVFSDIR hVfsCwd, const char *pszCwd,
818 PRTVFSFILE phVfsFile, PRTERRINFO pErrInfo);
819
820
821/** @} */
822
823RT_C_DECLS_END
824
825#endif /* !IPRT_INCLUDED_fsisomaker_h */
826
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