fsisomaker.h

Last change on this file was 106061, checked in by vboxsync, 2 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: 34.7 KB

Line
1	/** @file
2	* IPRT - ISO Image Maker.
3	*/
4
5	/*
6	* Copyright (C) 2017-2024 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
48	RT_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	*/
77	RTDECL(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	*/
85	RTDECL(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	*/
93	RTDECL(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	*/
102	RTDECL(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	*/
110	RTDECL(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	*/
120	RTDECL(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	*/
130	RTDECL(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	*/
140	RTDECL(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	*/
149	RTDECL(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	*/
158	RTDECL(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	*/
176	RTDECL(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	*/
185	RTDECL(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	*/
194	RTDECL(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	*/
204	RTDECL(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	*/
214	RTDECL(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	*/
230	RTDECL(int) RTFsIsoMakerSetSysAreaContent(RTFSISOMAKER hIsoMaker, void const *pvContent, size_t cbContent, uint32_t off);
231
232	/**
233	* String properties settable thru RTFsIsoMakerSetStringProp.
234	*/
235	typedef 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	*/
274	RTDECL(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	*/
284	RTDECL(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	*/
292	RTDECL(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	*/
308	RTDECL(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	*/
320	RTDECL(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	*/
329	RTDECL(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	*/
346	RTDECL(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	*/
363	RTDECL(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	*/
380	RTDECL(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	*/
390	RTDECL(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	*/
402	RTDECL(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	*/
418	RTDECL(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	*/
431	RTDECL(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	*/
445	RTDECL(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	*/
459	RTDECL(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	*/
477	RTDECL(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	*/
495	RTDECL(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	*/
510	RTDECL(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	*/
525	RTDECL(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	*/
548	RTDECL(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	*/
563	RTDECL(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	*/
582	RTDECL(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	*/
600	RTDECL(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	*/
618	RTDECL(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	*/
630	RTDECL(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	*/
655	RTDECL(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	*/
671	RTDECL(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	*/
686	RTDECL(int) RTFsIsoMakerBootCatSetFile(RTFSISOMAKER hIsoMaker, uint32_t idxObj);
687
688
689	/**
690	* ISO maker import results (RTFsIsoMakerImport).
691	*/
692	typedef 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. */
713	typedef 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	*/
729	RTDECL(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	*/
772	RTDECL(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	*/
785	RTDECL(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	*/
796	RTDECL(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	*/
817	RTDECL(int) RTFsIsoMakerCmdEx(unsigned cArgs, char *papszArgs, RTVFSDIR hVfsCwd, const char pszCwd,
818	PRTVFSFILE phVfsFile, PRTERRINFO pErrInfo);
819
820
821	/** @} */
822
823	RT_C_DECLS_END
824
825	#endif /* !IPRT_INCLUDED_fsisomaker_h */
826

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: