fsisomaker.h@ 93176

Last change on this file since 93176 was 93118, checked in by vboxsync, 3 years ago
IPRT/RTIsoMaker: Added an --name-setup-from-import option to better handle importing old ISOs without joliet present. We get into trouble when adding our files to the ISO in both primary iso and joliet space, since the guest might be inclined to show the joliet view (which is missing the files from the imported ISO).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 34.4 KB

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

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

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

Download in other formats: