fsisomaker.h@ 83941

Last change on this file since 83941 was 82968, checked in by vboxsync, 5 years ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 33.5 KB

Line
1	/** @file
2	* IPRT - ISO Image Maker.
3	*/
4
5	/*
6	* Copyright (C) 2017-2020 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	* Changes the file attribute (mode, owner, group) inherit style (from source).
134	*
135	* The strict style will use the exact attributes from the source, where as the
136	* non-strict (aka rational and default) style will use 0 for the owner and
137	* group IDs and normalize the mode bits along the lines of 'chmod a=rX',
138	* stripping set-uid/gid bitson files but preserving sticky ones on directories.
139	*
140	* When disabling strict style, the default dir and file modes will be restored
141	* to default values.
142	*
143	* @returns IRPT status code.
144	* @param hIsoMaker The ISO maker handle.
145	* @param fStrict Indicates strict (true) or non-strict (false)
146	* style.
147	*/
148	RTDECL(int) RTFsIsoMakerSetAttribInheritStyle(RTFSISOMAKER hIsoMaker, bool fStrict);
149
150	/**
151	* Sets the default file mode settings.
152	*
153	* @returns IRPT status code.
154	* @param hIsoMaker The ISO maker handle.
155	* @param fMode The default file mode.
156	*/
157	RTDECL(int) RTFsIsoMakerSetDefaultFileMode(RTFSISOMAKER hIsoMaker, RTFMODE fMode);
158
159	/**
160	* Sets the default dir mode settings.
161	*
162	* @returns IRPT status code.
163	* @param hIsoMaker The ISO maker handle.
164	* @param fMode The default dir mode.
165	*/
166	RTDECL(int) RTFsIsoMakerSetDefaultDirMode(RTFSISOMAKER hIsoMaker, RTFMODE fMode);
167
168	/**
169	* Sets the forced file mode, if @a fForce is true also the default mode is set.
170	*
171	* @returns IRPT status code.
172	* @param hIsoMaker The ISO maker handle.
173	* @param fMode The file mode.
174	* @param fForce Indicate whether forced mode is active or not.
175	*/
176	RTDECL(int) RTFsIsoMakerSetForcedFileMode(RTFSISOMAKER hIsoMaker, RTFMODE fMode, bool fForce);
177
178	/**
179	* Sets the forced dir mode, if @a fForce is true also the default mode is set.
180	*
181	* @returns IRPT status code.
182	* @param hIsoMaker The ISO maker handle.
183	* @param fMode The dir mode.
184	* @param fForce Indicate whether forced mode is active or not.
185	*/
186	RTDECL(int) RTFsIsoMakerSetForcedDirMode(RTFSISOMAKER hIsoMaker, RTFMODE fMode, bool fForce);
187
188	/**
189	* Sets the content of the system area, i.e. the first 32KB of the image.
190	*
191	* This can be used to put generic boot related stuff.
192	*
193	* @note Other settings may overwrite parts of the content (yet to be
194	* determined which).
195	*
196	* @returns IPRT status code
197	* @param hIsoMaker The ISO maker handle.
198	* @param pvContent The content to put in the system area.
199	* @param cbContent The size of the content.
200	* @param off The offset into the system area.
201	*/
202	RTDECL(int) RTFsIsoMakerSetSysAreaContent(RTFSISOMAKER hIsoMaker, void const *pvContent, size_t cbContent, uint32_t off);
203
204	/**
205	* String properties settable thru RTFsIsoMakerSetStringProp.
206	*/
207	typedef enum RTFSISOMAKERSTRINGPROP
208	{
209	/** The customary invalid zero value. */
210	RTFSISOMAKERSTRINGPROP_INVALID = 0,
211	/** The system identifier. */
212	RTFSISOMAKERSTRINGPROP_SYSTEM_ID,
213	/** The volume identifier(label). */
214	RTFSISOMAKERSTRINGPROP_VOLUME_ID,
215	/** The volume set identifier. */
216	RTFSISOMAKERSTRINGPROP_VOLUME_SET_ID,
217	/** The publisher ID (root file reference if it starts with '_'). */
218	RTFSISOMAKERSTRINGPROP_PUBLISHER_ID,
219	/** The data preparer ID (root file reference if it starts with '_'). */
220	RTFSISOMAKERSTRINGPROP_DATA_PREPARER_ID,
221	/** The application ID (root file reference if it starts with '_'). */
222	RTFSISOMAKERSTRINGPROP_APPLICATION_ID,
223	/** The copyright file ID. */
224	RTFSISOMAKERSTRINGPROP_COPYRIGHT_FILE_ID,
225	/** The abstract file ID. */
226	RTFSISOMAKERSTRINGPROP_ABSTRACT_FILE_ID,
227	/** The bibliographic file ID. */
228	RTFSISOMAKERSTRINGPROP_BIBLIOGRAPHIC_FILE_ID,
229	/** End of valid string property values. */
230	RTFSISOMAKERSTRINGPROP_END,
231	/** Make sure it's a 32-bit type. */
232	RTFSISOMAKERSTRINGPROP_32BIT_HACK = 0x7fffffff
233	} RTFSISOMAKERSTRINGPROP;
234
235	/**
236	* Sets a string property in one or more namespaces.
237	*
238	* @returns IPRT status code.
239	* @param hIsoMaker The ISO maker handle.
240	* @param enmStringProp The string property to set.
241	* @param fNamespaces The namespaces to set it in.
242	* @param pszValue The value to set it to. NULL is treated like an
243	* empty string. The value will be silently truncated
244	* to fit the available space.
245	*/
246	RTDECL(int) RTFsIsoMakerSetStringProp(RTFSISOMAKER hIsoMaker, RTFSISOMAKERSTRINGPROP enmStringProp,
247	uint32_t fNamespaces, const char *pszValue);
248
249	/**
250	* Specifies image padding.
251	*
252	* @returns IPRT status code.
253	* @param hIsoMaker The ISO maker handle.
254	* @param cSectors Number of sectors to pad the image with.
255	*/
256	RTDECL(int) RTFsIsoMakerSetImagePadding(RTFSISOMAKER hIsoMaker, uint32_t cSectors);
257
258	/**
259	* Resolves a path into a object ID.
260	*
261	* This will be doing the looking up using the specified object names rather
262	* than the version adjusted and mangled according to the namespace setup.
263	*
264	* @returns The object ID corresponding to @a pszPath, or UINT32_MAX if not
265	* found or invalid parameters.
266	* @param hIsoMaker The ISO maker instance.
267	* @param fNamespaces The namespace to resolve @a pszPath in. It's
268	* possible to specify multiple namespaces here, of
269	* course, but that's inefficient.
270	* @param pszPath The path to the object.
271	*/
272	RTDECL(uint32_t) RTFsIsoMakerGetObjIdxForPath(RTFSISOMAKER hIsoMaker, uint32_t fNamespaces, const char *pszPath);
273
274	/**
275	* Queries the configuration index of the boot catalog file object.
276	*
277	* The boot catalog file is created as necessary, thus this have to be a query
278	* rather than a getter since object creation may fail.
279	*
280	* @returns IPRT status code.
281	* @param hIsoMaker The ISO maker handle.
282	* @param pidxObj Where to return the configuration index.
283	*/
284	RTDECL(int) RTFsIsoMakerQueryObjIdxForBootCatalog(RTFSISOMAKER hIsoMaker, uint32_t *pidxObj);
285
286	/**
287	* Removes the specified object from the image.
288	*
289	* @returns IPRT status code.
290	* @param hIsoMaker The ISO maker instance.
291	* @param idxObj The index of the object to remove.
292	*/
293	RTDECL(int) RTFsIsoMakerObjRemove(RTFSISOMAKER hIsoMaker, uint32_t idxObj);
294
295	/**
296	* Sets the path (name) of an object in the selected namespaces.
297	*
298	* The name will be transformed as necessary.
299	*
300	* The initial implementation does not allow this function to be called more
301	* than once on an object.
302	*
303	* @returns IPRT status code.
304	* @param hIsoMaker The ISO maker handle.
305	* @param idxObj The configuration index of to name.
306	* @param fNamespaces The namespaces to apply the path to
307	* (RTFSISOMAKER_NAMESPACE_XXX).
308	* @param pszPath The path.
309	*/
310	RTDECL(int) RTFsIsoMakerObjSetPath(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint32_t fNamespaces, const char *pszPath);
311
312	/**
313	* Sets the name of an object in the selected namespaces, placing it under the
314	* given directory.
315	*
316	* The name will be transformed as necessary.
317	*
318	* @returns IPRT status code.
319	* @param hIsoMaker The ISO maker handle.
320	* @param idxObj The configuration index of to name.
321	* @param idxParentObj The parent directory object.
322	* @param fNamespaces The namespaces to apply the path to
323	* (RTFSISOMAKER_NAMESPACE_XXX).
324	* @param pszName The name.
325	* @param fNoNormalize Don't normalize the name (imported or such).
326	*/
327	RTDECL(int) RTFsIsoMakerObjSetNameAndParent(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint32_t idxParentObj,
328	uint32_t fNamespaces, const char *pszName, bool fNoNormalize);
329
330	/**
331	* Changes the rock ridge name for the object in the selected namespaces.
332	*
333	* The object must already be enetered into the namespaces by
334	* RTFsIsoMakerObjSetNameAndParent, RTFsIsoMakerObjSetPath or similar.
335	*
336	* @returns IPRT status code.
337	* @param hIsoMaker The ISO maker handle.
338	* @param idxObj The configuration index of to name.
339	* @param fNamespaces The namespaces to apply the path to
340	* (RTFSISOMAKER_NAMESPACE_XXX).
341	* @param pszRockName The rock ridge name. Passing NULL or an empty
342	* string will restore the specified name.
343	*/
344	RTDECL(int) RTFsIsoMakerObjSetRockName(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint32_t fNamespaces, const char *pszRockName);
345
346	/**
347	* Enables or disable syslinux boot info table patching of a file.
348	*
349	* @returns IPRT status code.
350	* @param hIsoMaker The ISO maker handle.
351	* @param idxObj The configuration index.
352	* @param fEnable Whether to enable or disable patching.
353	*/
354	RTDECL(int) RTFsIsoMakerObjEnableBootInfoTablePatching(RTFSISOMAKER hIsoMaker, uint32_t idxObj, bool fEnable);
355
356	/**
357	* Gets the data size of an object.
358	*
359	* Currently only supported on file objects.
360	*
361	* @returns IPRT status code.
362	* @param hIsoMaker The ISO maker handle.
363	* @param idxObj The configuration index.
364	* @param pcbData Where to return the size.
365	*/
366	RTDECL(int) RTFsIsoMakerObjQueryDataSize(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint64_t *pcbData);
367
368	/**
369	* Adds an unnamed directory to the image.
370	*
371	* The directory must explictly be entered into the desired namespaces.
372	*
373	* @returns IPRT status code
374	* @param hIsoMaker The ISO maker handle.
375	* @param pObjInfo Pointer to object attributes, must be set to
376	* UNIX. The size and hardlink counts are ignored.
377	* Optional.
378	* @param pidxObj Where to return the configuration index of the
379	* directory.
380	* @sa RTFsIsoMakerAddDir, RTFsIsoMakerObjSetPath
381	*/
382	RTDECL(int) RTFsIsoMakerAddUnnamedDir(RTFSISOMAKER hIsoMaker, PCRTFSOBJINFO pObjInfo, uint32_t *pidxObj);
383
384	/**
385	* Adds a directory to the image in all namespaces and default attributes.
386	*
387	* @returns IPRT status code
388	* @param hIsoMaker The ISO maker handle.
389	* @param pszDir The path (UTF-8) to the directory in the ISO.
390	*
391	* @param pidxObj Where to return the configuration index of the
392	* directory. Optional.
393	* @sa RTFsIsoMakerAddUnnamedDir, RTFsIsoMakerObjSetPath
394	*/
395	RTDECL(int) RTFsIsoMakerAddDir(RTFSISOMAKER hIsoMaker, const char pszDir, uint32_t pidxObj);
396
397	/**
398	* Adds an unnamed file to the image that's backed by a host file.
399	*
400	* The file must explictly be entered into the desired namespaces.
401	*
402	* @returns IPRT status code
403	* @param hIsoMaker The ISO maker handle.
404	* @param pszSrcFile The source file path. VFS chain spec allowed.
405	* @param pidxObj Where to return the configuration index of the
406	* directory.
407	* @sa RTFsIsoMakerAddFile, RTFsIsoMakerObjSetPath
408	*/
409	RTDECL(int) RTFsIsoMakerAddUnnamedFileWithSrcPath(RTFSISOMAKER hIsoMaker, const char pszSrcFile, uint32_t pidxObj);
410
411	/**
412	* Adds an unnamed file to the image that's backed by a VFS file.
413	*
414	* The file must explictly be entered into the desired namespaces.
415	*
416	* @returns IPRT status code
417	* @param hIsoMaker The ISO maker handle.
418	* @param hVfsFileSrc The source file handle.
419	* @param pidxObj Where to return the configuration index of the
420	* directory.
421	* @sa RTFsIsoMakerAddUnnamedFileWithSrcPath, RTFsIsoMakerObjSetPath
422	*/
423	RTDECL(int) RTFsIsoMakerAddUnnamedFileWithVfsFile(RTFSISOMAKER hIsoMaker, RTVFSFILE hVfsFileSrc, uint32_t *pidxObj);
424
425	/**
426	* Adds an unnamed file to the image that's backed by a portion of a common
427	* source file.
428	*
429	* The file must explictly be entered into the desired namespaces.
430	*
431	* @returns IPRT status code
432	* @param hIsoMaker The ISO maker handle.
433	* @param idxCommonSrc The common source file index.
434	* @param offData The offset of the data in the source file.
435	* @param cbData The file size.
436	* @param pObjInfo Pointer to file info. Optional.
437	* @param pidxObj Where to return the configuration index of the
438	* directory.
439	* @sa RTFsIsoMakerAddUnnamedFileWithSrcPath, RTFsIsoMakerObjSetPath
440	*/
441	RTDECL(int) RTFsIsoMakerAddUnnamedFileWithCommonSrc(RTFSISOMAKER hIsoMaker, uint32_t idxCommonSrc,
442	uint64_t offData, uint64_t cbData, PCRTFSOBJINFO pObjInfo, uint32_t *pidxObj);
443
444	/**
445	* Adds a common source file.
446	*
447	* Using RTFsIsoMakerAddUnnamedFileWithCommonSrc a sections common source file
448	* can be referenced to make up other files. The typical use case is when
449	* importing data from an existing ISO.
450	*
451	* @returns IPRT status code
452	* @param hIsoMaker The ISO maker handle.
453	* @param hVfsFile VFS handle of the common source. (A reference
454	* is added, none consumed.)
455	* @param pidxCommonSrc Where to return the assigned common source
456	* index. This is used to reference the file.
457	* @sa RTFsIsoMakerAddUnnamedFileWithCommonSrc
458	*/
459	RTDECL(int) RTFsIsoMakerAddCommonSourceFile(RTFSISOMAKER hIsoMaker, RTVFSFILE hVfsFile, uint32_t *pidxCommonSrc);
460
461	/**
462	* Adds a file that's backed by a host file to the image in all namespaces and
463	* with attributes taken from the source file.
464	*
465	* @returns IPRT status code
466	* @param hIsoMaker The ISO maker handle.
467	* @param pszFile The path to the file in the image.
468	* @param pszSrcFile The source file path. VFS chain spec allowed.
469	* @param pidxObj Where to return the configuration index of the file.
470	* Optional
471	* @sa RTFsIsoMakerAddFileWithVfsFile,
472	* RTFsIsoMakerAddUnnamedFileWithSrcPath
473	*/
474	RTDECL(int) RTFsIsoMakerAddFileWithSrcPath(RTFSISOMAKER hIsoMaker, const char pszFile, const char pszSrcFile, uint32_t *pidxObj);
475
476	/**
477	* Adds a file that's backed by a VFS file to the image in all namespaces and
478	* with attributes taken from the source file.
479	*
480	* @returns IPRT status code
481	* @param hIsoMaker The ISO maker handle.
482	* @param pszFile The path to the file in the image.
483	* @param hVfsFileSrc The source file handle.
484	* @param pidxObj Where to return the configuration index of the file.
485	* Optional.
486	* @sa RTFsIsoMakerAddUnnamedFileWithVfsFile,
487	* RTFsIsoMakerAddFileWithSrcPath
488	*/
489	RTDECL(int) RTFsIsoMakerAddFileWithVfsFile(RTFSISOMAKER hIsoMaker, const char pszFile, RTVFSFILE hVfsFileSrc, uint32_t pidxObj);
490
491	/**
492	* Adds an unnamed symbolic link to the image.
493	*
494	* The symlink must explictly be entered into the desired namespaces. Please
495	* note that it is not possible to enter a symbolic link into an ISO 9660
496	* namespace where rock ridge extensions are disabled, since symbolic links
497	* depend on rock ridge. For HFS and UDF there is no such requirement.
498	*
499	* Will fail if no namespace is configured that supports symlinks.
500	*
501	* @returns IPRT status code
502	* @retval VERR_ISOMK_SYMLINK_SUPPORT_DISABLED if not supported.
503	* @param hIsoMaker The ISO maker handle.
504	* @param pObjInfo Pointer to object attributes, must be set to
505	* UNIX. The size and hardlink counts are ignored.
506	* Optional.
507	* @param pszTarget The symbolic link target (UTF-8).
508	* @param pidxObj Where to return the configuration index of the
509	* directory.
510	* @sa RTFsIsoMakerAddSymlink, RTFsIsoMakerObjSetPath
511	*/
512	RTDECL(int) RTFsIsoMakerAddUnnamedSymlink(RTFSISOMAKER hIsoMaker, PCRTFSOBJINFO pObjInfo, const char pszTarget, uint32_t pidxObj);
513
514	/**
515	* Adds a directory to the image in all namespaces and default attributes.
516	*
517	* Will fail if no namespace is configured that supports symlinks.
518	*
519	* @returns IPRT status code
520	* @param hIsoMaker The ISO maker handle.
521	* @param pszSymlink The path (UTF-8) to the symlink in the ISO.
522	* @param pszTarget The symlink target (UTF-8).
523	* @param pidxObj Where to return the configuration index of the
524	* directory. Optional.
525	* @sa RTFsIsoMakerAddUnnamedSymlink, RTFsIsoMakerObjSetPath
526	*/
527	RTDECL(int) RTFsIsoMakerAddSymlink(RTFSISOMAKER hIsoMaker, const char pszSymlink, const char pszTarget, uint32_t *pidxObj);
528
529	/**
530	* Modifies the mode mask for a given path in one or more namespaces.
531	*
532	* The mode mask is used by rock ridge, UDF and HFS.
533	*
534	* @returns IPRT status code.
535	* @retval VWRN_NOT_FOUND if the path wasn't found in any of the specified
536	* namespaces.
537	*
538	* @param hIsoMaker The ISO maker handler.
539	* @param pszPath The path which mode mask should be modified.
540	* @param fNamespaces The namespaces to set it in.
541	* @param fSet The mode bits to set.
542	* @param fUnset The mode bits to clear (applied first).
543	* @param fFlags Reserved, MBZ.
544	* @param pcHits Where to return number of paths found. Optional.
545	*/
546	RTDECL(int) RTFsIsoMakerSetPathMode(RTFSISOMAKER hIsoMaker, const char *pszPath, uint32_t fNamespaces,
547	RTFMODE fSet, RTFMODE fUnset, uint32_t fFlags, uint32_t *pcHits);
548
549	/**
550	* Modifies the owner ID for a given path in one or more namespaces.
551	*
552	* The owner ID is used by rock ridge, UDF and HFS.
553	*
554	* @returns IPRT status code.
555	* @retval VWRN_NOT_FOUND if the path wasn't found in any of the specified
556	* namespaces.
557	*
558	* @param hIsoMaker The ISO maker handler.
559	* @param pszPath The path which mode mask should be modified.
560	* @param fNamespaces The namespaces to set it in.
561	* @param idOwner The new owner ID to set.
562	* @param pcHits Where to return number of paths found. Optional.
563	*/
564	RTDECL(int) RTFsIsoMakerSetPathOwnerId(RTFSISOMAKER hIsoMaker, const char *pszPath, uint32_t fNamespaces,
565	RTUID idOwner, uint32_t *pcHits);
566
567	/**
568	* Modifies the group ID for a given path in one or more namespaces.
569	*
570	* The group ID is used by rock ridge, UDF and HFS.
571	*
572	* @returns IPRT status code.
573	* @retval VWRN_NOT_FOUND if the path wasn't found in any of the specified
574	* namespaces.
575	*
576	* @param hIsoMaker The ISO maker handler.
577	* @param pszPath The path which mode mask should be modified.
578	* @param fNamespaces The namespaces to set it in.
579	* @param idGroup The new group ID to set.
580	* @param pcHits Where to return number of paths found. Optional.
581	*/
582	RTDECL(int) RTFsIsoMakerSetPathGroupId(RTFSISOMAKER hIsoMaker, const char *pszPath, uint32_t fNamespaces,
583	RTGID idGroup, uint32_t *pcHits);
584
585	/**
586	* Set the validation entry of the boot catalog (this is the first entry).
587	*
588	* @returns IPRT status code.
589	* @param hIsoMaker The ISO maker handle.
590	* @param idPlatform The platform ID
591	* (ISO9660_ELTORITO_PLATFORM_ID_XXX).
592	* @param pszString CD/DVD-ROM identifier. Optional.
593	*/
594	RTDECL(int) RTFsIsoMakerBootCatSetValidationEntry(RTFSISOMAKER hIsoMaker, uint8_t idPlatform, const char *pszString);
595
596	/**
597	* Set the validation entry of the boot catalog (this is the first entry).
598	*
599	* @returns IPRT status code.
600	* @param hIsoMaker The ISO maker handle.
601	* @param idxBootCat The boot catalog entry. Zero and two are
602	* invalid. Must be less than 63.
603	* @param idxImageObj The configuration index of the boot image.
604	* @param bBootMediaType The media type and flag (not for entry 1)
605	* (ISO9660_ELTORITO_BOOT_MEDIA_TYPE_XXX,
606	* ISO9660_ELTORITO_BOOT_MEDIA_F_XXX).
607	* @param bSystemType The partitiona table system ID.
608	* @param fBootable Whether it's a bootable entry or if we just want
609	* the BIOS to setup the emulation without booting
610	* it.
611	* @param uLoadSeg The load address divided by 0x10 (i.e. the real
612	* mode segment number).
613	* @param cSectorsToLoad Number of emulated sectors to load.
614	* @param bSelCritType The selection criteria type, if none pass
615	* ISO9660_ELTORITO_SEL_CRIT_TYPE_NONE.
616	* @param pvSelCritData Pointer to the selection criteria data.
617	* @param cbSelCritData Size of the selection criteria data.
618	*/
619	RTDECL(int) RTFsIsoMakerBootCatSetSectionEntry(RTFSISOMAKER hIsoMaker, uint32_t idxBootCat, uint32_t idxImageObj,
620	uint8_t bBootMediaType, uint8_t bSystemType, bool fBootable,
621	uint16_t uLoadSeg, uint16_t cSectorsToLoad,
622	uint8_t bSelCritType, void const *pvSelCritData, size_t cbSelCritData);
623
624	/**
625	* Set the validation entry of the boot catalog (this is the first entry).
626	*
627	* @returns IPRT status code.
628	* @param hIsoMaker The ISO maker handle.
629	* @param idxBootCat The boot catalog entry.
630	* @param cEntries Number of entries in the section.
631	* @param idPlatform The platform ID
632	* (ISO9660_ELTORITO_PLATFORM_ID_XXX).
633	* @param pszString Section identifier or something. Optional.
634	*/
635	RTDECL(int) RTFsIsoMakerBootCatSetSectionHeaderEntry(RTFSISOMAKER hIsoMaker, uint32_t idxBootCat, uint32_t cEntries,
636	uint8_t idPlatform, const char *pszString);
637
638	/**
639	* Sets the boot catalog backing file.
640	*
641	* The content of the given file will be discarded and replaced with the boot
642	* catalog, the naming and file attributes (other than size) will be retained.
643	*
644	* This API exists mainly to assist when importing ISOs.
645	*
646	* @returns IPRT status code.
647	* @param hIsoMaker The ISO maker handle.
648	* @param idxObj The configuration index of the file.
649	*/
650	RTDECL(int) RTFsIsoMakerBootCatSetFile(RTFSISOMAKER hIsoMaker, uint32_t idxObj);
651
652
653	/**
654	* ISO maker import results (RTFsIsoMakerImport).
655	*/
656	typedef struct RTFSISOMAKERIMPORTRESULTS
657	{
658	/** Number of names added. */
659	uint32_t cAddedNames;
660	/** Number of directories added. */
661	uint32_t cAddedDirs;
662	/** Amount of added data blocks, files only. */
663	uint64_t cbAddedDataBlocks;
664	/** Number of unique files added (unique in terms of data location). */
665	uint32_t cAddedFiles;
666	/** Number of symbolic links added. */
667	uint32_t cAddedSymlinks;
668	/** Number of imported boot catalog entries. */
669	uint32_t cBootCatEntries;
670	/** Number of system area bytes imported (from offset zero). */
671	uint32_t cbSysArea;
672
673	/** Number of import errors. */
674	uint32_t cErrors;
675	} RTFSISOMAKERIMPORTRESULTS;
676	/** Pointer to ISO maker import results. */
677	typedef RTFSISOMAKERIMPORTRESULTS *PRTFSISOMAKERIMPORTRESULTS;
678
679	/**
680	* Imports an existing ISO.
681	*
682	* Just like other source files, the existing image must remain present and
683	* unmodified till the ISO maker is done with it.
684	*
685	* @returns IRPT status code.
686	* @param hIsoMaker The ISO maker handle.
687	* @param hIsoFile VFS file handle to the existing image to import / clone.
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, RTVFSFILE hIsoFile, 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 hVfsCwd The current working directory to assume when processing
772	* relative file/dir references. Pass NIL_RTVFSDIR to use
773	* the current CWD of the process.
774	* @param pszCwd Path to @a hVfsCwdDir. Use for error reporting and
775	* optimizing the open file count if possible.
776	* @param phVfsFile Where to return the virtual ISO. Pass NULL to for
777	* normal operation (creates file on disk).
778	* @param pErrInfo Where to return extended error information in the
779	* virtual ISO mode.
780	*/
781	RTDECL(int) RTFsIsoMakerCmdEx(unsigned cArgs, char *papszArgs, RTVFSDIR hVfsCwd, const char pszCwd,
782	PRTVFSFILE phVfsFile, PRTERRINFO pErrInfo);
783
784
785	/** @} */
786
787	RT_C_DECLS_END
788
789	#endif /* !IPRT_INCLUDED_fsisomaker_h */
790

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

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

Download in other formats: