fsisomaker.h@ 68836

Last change on this file since 68836 was 68817, checked in by vboxsync, 7 years ago
IPRT/isomaker: Added default 16 sector image padding (allegedly a workaround for various read ahead bugs) and a bunch of other things.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 33.2 KB

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

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

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

Download in other formats: