fsisomaker.h@ 77118

Last change on this file since 77118 was 76585, checked in by vboxsync, 6 years ago
*: scm --fix-header-guard-endif
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 33.4 KB

Line
1	/** @file
2	* IPRT - ISO Image Maker.
3	*/
4
5	/*
6	* Copyright (C) 2017-2019 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	*/
326	RTDECL(int) RTFsIsoMakerObjSetNameAndParent(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint32_t idxParentObj,
327	uint32_t fNamespaces, const char *pszName);
328
329	/**
330	* Changes the rock ridge name for the object in the selected namespaces.
331	*
332	* The object must already be enetered into the namespaces by
333	* RTFsIsoMakerObjSetNameAndParent, RTFsIsoMakerObjSetPath or similar.
334	*
335	* @returns IPRT status code.
336	* @param hIsoMaker The ISO maker handle.
337	* @param idxObj The configuration index of to name.
338	* @param fNamespaces The namespaces to apply the path to
339	* (RTFSISOMAKER_NAMESPACE_XXX).
340	* @param pszRockName The rock ridge name. Passing NULL or an empty
341	* string will restore the specified name.
342	*/
343	RTDECL(int) RTFsIsoMakerObjSetRockName(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint32_t fNamespaces, const char *pszRockName);
344
345	/**
346	* Enables or disable syslinux boot info table patching of a file.
347	*
348	* @returns IPRT status code.
349	* @param hIsoMaker The ISO maker handle.
350	* @param idxObj The configuration index.
351	* @param fEnable Whether to enable or disable patching.
352	*/
353	RTDECL(int) RTFsIsoMakerObjEnableBootInfoTablePatching(RTFSISOMAKER hIsoMaker, uint32_t idxObj, bool fEnable);
354
355	/**
356	* Gets the data size of an object.
357	*
358	* Currently only supported on file objects.
359	*
360	* @returns IPRT status code.
361	* @param hIsoMaker The ISO maker handle.
362	* @param idxObj The configuration index.
363	* @param pcbData Where to return the size.
364	*/
365	RTDECL(int) RTFsIsoMakerObjQueryDataSize(RTFSISOMAKER hIsoMaker, uint32_t idxObj, uint64_t *pcbData);
366
367	/**
368	* Adds an unnamed directory to the image.
369	*
370	* The directory must explictly be entered into the desired namespaces.
371	*
372	* @returns IPRT status code
373	* @param hIsoMaker The ISO maker handle.
374	* @param pObjInfo Pointer to object attributes, must be set to
375	* UNIX. The size and hardlink counts are ignored.
376	* Optional.
377	* @param pidxObj Where to return the configuration index of the
378	* directory.
379	* @sa RTFsIsoMakerAddDir, RTFsIsoMakerObjSetPath
380	*/
381	RTDECL(int) RTFsIsoMakerAddUnnamedDir(RTFSISOMAKER hIsoMaker, PCRTFSOBJINFO pObjInfo, uint32_t *pidxObj);
382
383	/**
384	* Adds a directory to the image in all namespaces and default attributes.
385	*
386	* @returns IPRT status code
387	* @param hIsoMaker The ISO maker handle.
388	* @param pszDir The path (UTF-8) to the directory in the ISO.
389	*
390	* @param pidxObj Where to return the configuration index of the
391	* directory. Optional.
392	* @sa RTFsIsoMakerAddUnnamedDir, RTFsIsoMakerObjSetPath
393	*/
394	RTDECL(int) RTFsIsoMakerAddDir(RTFSISOMAKER hIsoMaker, const char pszDir, uint32_t pidxObj);
395
396	/**
397	* Adds an unnamed file to the image that's backed by a host file.
398	*
399	* The file must explictly be entered into the desired namespaces.
400	*
401	* @returns IPRT status code
402	* @param hIsoMaker The ISO maker handle.
403	* @param pszSrcFile The source file path. VFS chain spec allowed.
404	* @param pidxObj Where to return the configuration index of the
405	* directory.
406	* @sa RTFsIsoMakerAddFile, RTFsIsoMakerObjSetPath
407	*/
408	RTDECL(int) RTFsIsoMakerAddUnnamedFileWithSrcPath(RTFSISOMAKER hIsoMaker, const char pszSrcFile, uint32_t pidxObj);
409
410	/**
411	* Adds an unnamed file to the image that's backed by a VFS file.
412	*
413	* The file must explictly be entered into the desired namespaces.
414	*
415	* @returns IPRT status code
416	* @param hIsoMaker The ISO maker handle.
417	* @param hVfsFileSrc The source file handle.
418	* @param pidxObj Where to return the configuration index of the
419	* directory.
420	* @sa RTFsIsoMakerAddUnnamedFileWithSrcPath, RTFsIsoMakerObjSetPath
421	*/
422	RTDECL(int) RTFsIsoMakerAddUnnamedFileWithVfsFile(RTFSISOMAKER hIsoMaker, RTVFSFILE hVfsFileSrc, uint32_t *pidxObj);
423
424	/**
425	* Adds an unnamed file to the image that's backed by a portion of a common
426	* source file.
427	*
428	* The file must explictly be entered into the desired namespaces.
429	*
430	* @returns IPRT status code
431	* @param hIsoMaker The ISO maker handle.
432	* @param idxCommonSrc The common source file index.
433	* @param offData The offset of the data in the source file.
434	* @param cbData The file size.
435	* @param pObjInfo Pointer to file info. Optional.
436	* @param pidxObj Where to return the configuration index of the
437	* directory.
438	* @sa RTFsIsoMakerAddUnnamedFileWithSrcPath, RTFsIsoMakerObjSetPath
439	*/
440	RTDECL(int) RTFsIsoMakerAddUnnamedFileWithCommonSrc(RTFSISOMAKER hIsoMaker, uint32_t idxCommonSrc,
441	uint64_t offData, uint64_t cbData, PCRTFSOBJINFO pObjInfo, uint32_t *pidxObj);
442
443	/**
444	* Adds a common source file.
445	*
446	* Using RTFsIsoMakerAddUnnamedFileWithCommonSrc a sections common source file
447	* can be referenced to make up other files. The typical use case is when
448	* importing data from an existing ISO.
449	*
450	* @returns IPRT status code
451	* @param hIsoMaker The ISO maker handle.
452	* @param hVfsFile VFS handle of the common source. (A reference
453	* is added, none consumed.)
454	* @param pidxCommonSrc Where to return the assigned common source
455	* index. This is used to reference the file.
456	* @sa RTFsIsoMakerAddUnnamedFileWithCommonSrc
457	*/
458	RTDECL(int) RTFsIsoMakerAddCommonSourceFile(RTFSISOMAKER hIsoMaker, RTVFSFILE hVfsFile, uint32_t *pidxCommonSrc);
459
460	/**
461	* Adds a file that's backed by a host file to the image in all namespaces and
462	* with attributes taken from the source file.
463	*
464	* @returns IPRT status code
465	* @param hIsoMaker The ISO maker handle.
466	* @param pszFile The path to the file in the image.
467	* @param pszSrcFile The source file path. VFS chain spec allowed.
468	* @param pidxObj Where to return the configuration index of the file.
469	* Optional
470	* @sa RTFsIsoMakerAddFileWithVfsFile,
471	* RTFsIsoMakerAddUnnamedFileWithSrcPath
472	*/
473	RTDECL(int) RTFsIsoMakerAddFileWithSrcPath(RTFSISOMAKER hIsoMaker, const char pszFile, const char pszSrcFile, uint32_t *pidxObj);
474
475	/**
476	* Adds a file that's backed by a VFS file to the image in all namespaces and
477	* with attributes taken from the source file.
478	*
479	* @returns IPRT status code
480	* @param hIsoMaker The ISO maker handle.
481	* @param pszFile The path to the file in the image.
482	* @param hVfsFileSrc The source file handle.
483	* @param pidxObj Where to return the configuration index of the file.
484	* Optional.
485	* @sa RTFsIsoMakerAddUnnamedFileWithVfsFile,
486	* RTFsIsoMakerAddFileWithSrcPath
487	*/
488	RTDECL(int) RTFsIsoMakerAddFileWithVfsFile(RTFSISOMAKER hIsoMaker, const char pszFile, RTVFSFILE hVfsFileSrc, uint32_t pidxObj);
489
490	/**
491	* Adds an unnamed symbolic link to the image.
492	*
493	* The symlink must explictly be entered into the desired namespaces. Please
494	* note that it is not possible to enter a symbolic link into an ISO 9660
495	* namespace where rock ridge extensions are disabled, since symbolic links
496	* depend on rock ridge. For HFS and UDF there is no such requirement.
497	*
498	* Will fail if no namespace is configured that supports symlinks.
499	*
500	* @returns IPRT status code
501	* @retval VERR_ISOMK_SYMLINK_SUPPORT_DISABLED if not supported.
502	* @param hIsoMaker The ISO maker handle.
503	* @param pObjInfo Pointer to object attributes, must be set to
504	* UNIX. The size and hardlink counts are ignored.
505	* Optional.
506	* @param pszTarget The symbolic link target (UTF-8).
507	* @param pidxObj Where to return the configuration index of the
508	* directory.
509	* @sa RTFsIsoMakerAddSymlink, RTFsIsoMakerObjSetPath
510	*/
511	RTDECL(int) RTFsIsoMakerAddUnnamedSymlink(RTFSISOMAKER hIsoMaker, PCRTFSOBJINFO pObjInfo, const char pszTarget, uint32_t pidxObj);
512
513	/**
514	* Adds a directory to the image in all namespaces and default attributes.
515	*
516	* Will fail if no namespace is configured that supports symlinks.
517	*
518	* @returns IPRT status code
519	* @param hIsoMaker The ISO maker handle.
520	* @param pszSymlink The path (UTF-8) to the symlink in the ISO.
521	* @param pszTarget The symlink target (UTF-8).
522	* @param pidxObj Where to return the configuration index of the
523	* directory. Optional.
524	* @sa RTFsIsoMakerAddUnnamedSymlink, RTFsIsoMakerObjSetPath
525	*/
526	RTDECL(int) RTFsIsoMakerAddSymlink(RTFSISOMAKER hIsoMaker, const char pszSymlink, const char pszTarget, uint32_t *pidxObj);
527
528	/**
529	* Modifies the mode mask for a given path in one or more namespaces.
530	*
531	* The mode mask is used by rock ridge, UDF and HFS.
532	*
533	* @returns IPRT status code.
534	* @retval VWRN_NOT_FOUND if the path wasn't found in any of the specified
535	* namespaces.
536	*
537	* @param hIsoMaker The ISO maker handler.
538	* @param pszPath The path which mode mask should be modified.
539	* @param fNamespaces The namespaces to set it in.
540	* @param fSet The mode bits to set.
541	* @param fUnset The mode bits to clear (applied first).
542	* @param fFlags Reserved, MBZ.
543	* @param pcHits Where to return number of paths found. Optional.
544	*/
545	RTDECL(int) RTFsIsoMakerSetPathMode(RTFSISOMAKER hIsoMaker, const char *pszPath, uint32_t fNamespaces,
546	RTFMODE fSet, RTFMODE fUnset, uint32_t fFlags, uint32_t *pcHits);
547
548	/**
549	* Modifies the owner ID for a given path in one or more namespaces.
550	*
551	* The owner ID is used by rock ridge, UDF and HFS.
552	*
553	* @returns IPRT status code.
554	* @retval VWRN_NOT_FOUND if the path wasn't found in any of the specified
555	* namespaces.
556	*
557	* @param hIsoMaker The ISO maker handler.
558	* @param pszPath The path which mode mask should be modified.
559	* @param fNamespaces The namespaces to set it in.
560	* @param idOwner The new owner ID to set.
561	* @param pcHits Where to return number of paths found. Optional.
562	*/
563	RTDECL(int) RTFsIsoMakerSetPathOwnerId(RTFSISOMAKER hIsoMaker, const char *pszPath, uint32_t fNamespaces,
564	RTUID idOwner, uint32_t *pcHits);
565
566	/**
567	* Modifies the group ID for a given path in one or more namespaces.
568	*
569	* The group ID is used by rock ridge, UDF and HFS.
570	*
571	* @returns IPRT status code.
572	* @retval VWRN_NOT_FOUND if the path wasn't found in any of the specified
573	* namespaces.
574	*
575	* @param hIsoMaker The ISO maker handler.
576	* @param pszPath The path which mode mask should be modified.
577	* @param fNamespaces The namespaces to set it in.
578	* @param idGroup The new group ID to set.
579	* @param pcHits Where to return number of paths found. Optional.
580	*/
581	RTDECL(int) RTFsIsoMakerSetPathGroupId(RTFSISOMAKER hIsoMaker, const char *pszPath, uint32_t fNamespaces,
582	RTGID idGroup, uint32_t *pcHits);
583
584	/**
585	* Set the validation entry of the boot catalog (this is the first entry).
586	*
587	* @returns IPRT status code.
588	* @param hIsoMaker The ISO maker handle.
589	* @param idPlatform The platform ID
590	* (ISO9660_ELTORITO_PLATFORM_ID_XXX).
591	* @param pszString CD/DVD-ROM identifier. Optional.
592	*/
593	RTDECL(int) RTFsIsoMakerBootCatSetValidationEntry(RTFSISOMAKER hIsoMaker, uint8_t idPlatform, const char *pszString);
594
595	/**
596	* Set the validation entry of the boot catalog (this is the first entry).
597	*
598	* @returns IPRT status code.
599	* @param hIsoMaker The ISO maker handle.
600	* @param idxBootCat The boot catalog entry. Zero and two are
601	* invalid. Must be less than 63.
602	* @param idxImageObj The configuration index of the boot image.
603	* @param bBootMediaType The media type and flag (not for entry 1)
604	* (ISO9660_ELTORITO_BOOT_MEDIA_TYPE_XXX,
605	* ISO9660_ELTORITO_BOOT_MEDIA_F_XXX).
606	* @param bSystemType The partitiona table system ID.
607	* @param fBootable Whether it's a bootable entry or if we just want
608	* the BIOS to setup the emulation without booting
609	* it.
610	* @param uLoadSeg The load address divided by 0x10 (i.e. the real
611	* mode segment number).
612	* @param cSectorsToLoad Number of emulated sectors to load.
613	* @param bSelCritType The selection criteria type, if none pass
614	* ISO9660_ELTORITO_SEL_CRIT_TYPE_NONE.
615	* @param pvSelCritData Pointer to the selection criteria data.
616	* @param cbSelCritData Size of the selection criteria data.
617	*/
618	RTDECL(int) RTFsIsoMakerBootCatSetSectionEntry(RTFSISOMAKER hIsoMaker, uint32_t idxBootCat, uint32_t idxImageObj,
619	uint8_t bBootMediaType, uint8_t bSystemType, bool fBootable,
620	uint16_t uLoadSeg, uint16_t cSectorsToLoad,
621	uint8_t bSelCritType, void const *pvSelCritData, size_t cbSelCritData);
622
623	/**
624	* Set the validation entry of the boot catalog (this is the first entry).
625	*
626	* @returns IPRT status code.
627	* @param hIsoMaker The ISO maker handle.
628	* @param idxBootCat The boot catalog entry.
629	* @param cEntries Number of entries in the section.
630	* @param idPlatform The platform ID
631	* (ISO9660_ELTORITO_PLATFORM_ID_XXX).
632	* @param pszString Section identifier or something. Optional.
633	*/
634	RTDECL(int) RTFsIsoMakerBootCatSetSectionHeaderEntry(RTFSISOMAKER hIsoMaker, uint32_t idxBootCat, uint32_t cEntries,
635	uint8_t idPlatform, const char *pszString);
636
637	/**
638	* Sets the boot catalog backing file.
639	*
640	* The content of the given file will be discarded and replaced with the boot
641	* catalog, the naming and file attributes (other than size) will be retained.
642	*
643	* This API exists mainly to assist when importing ISOs.
644	*
645	* @returns IPRT status code.
646	* @param hIsoMaker The ISO maker handle.
647	* @param idxObj The configuration index of the file.
648	*/
649	RTDECL(int) RTFsIsoMakerBootCatSetFile(RTFSISOMAKER hIsoMaker, uint32_t idxObj);
650
651
652	/**
653	* ISO maker import results (RTFsIsoMakerImport).
654	*/
655	typedef struct RTFSISOMAKERIMPORTRESULTS
656	{
657	/** Number of names added. */
658	uint32_t cAddedNames;
659	/** Number of directories added. */
660	uint32_t cAddedDirs;
661	/** Amount of added data blocks, files only. */
662	uint64_t cbAddedDataBlocks;
663	/** Number of unique files added (unique in terms of data location). */
664	uint32_t cAddedFiles;
665	/** Number of symbolic links added. */
666	uint32_t cAddedSymlinks;
667	/** Number of imported boot catalog entries. */
668	uint32_t cBootCatEntries;
669	/** Number of system area bytes imported (from offset zero). */
670	uint32_t cbSysArea;
671
672	/** Number of import errors. */
673	uint32_t cErrors;
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 hIsoFile VFS file handle to the existing image to import / clone.
687	* @param fFlags Reserved for the future, MBZ.
688	* @param pResults Where to return import results.
689	* @param pErrInfo Where to return additional error information.
690	* Optional.
691	*/
692	RTDECL(int) RTFsIsoMakerImport(RTFSISOMAKER hIsoMaker, RTVFSFILE hIsoFile, uint32_t fFlags,
693	PRTFSISOMAKERIMPORTRESULTS pResults, PRTERRINFO pErrInfo);
694
695	/** @name RTFSISOMK_IMPORT_F_XXX - Flags for RTFsIsoMakerImport.
696	* @{ */
697	#define RTFSISOMK_IMPORT_F_NO_PRIMARY_ISO RT_BIT_32(0) /*< Skip the primary ISO-9660 namespace (rock ridge included). /
698	#define RTFSISOMK_IMPORT_F_NO_JOLIET RT_BIT_32(1) /*< Skip the joliet namespace. /
699	#define RTFSISOMK_IMPORT_F_NO_ROCK_RIDGE RT_BIT_32(2) /*< Skip rock ridge (both primary and joliet). /
700	#define RTFSISOMK_IMPORT_F_NO_UDF RT_BIT_32(3) /*< Skip the UDF namespace. /
701	#define RTFSISOMK_IMPORT_F_NO_HFS RT_BIT_32(4) /*< Skip the HFS namespace. /
702	#define RTFSISOMK_IMPORT_F_NO_BOOT RT_BIT_32(5) /*< Skip importing El Torito boot stuff. /
703	#define RTFSISOMK_IMPORT_F_NO_SYS_AREA RT_BIT_32(6) /*< Skip importing the system area (first 32KB). /
704
705	#define RTFSISOMK_IMPORT_F_NO_SYSTEM_ID RT_BIT_32(7) /*< Don't import the system ID primary descriptor field. /
706	#define RTFSISOMK_IMPORT_F_NO_VOLUME_ID RT_BIT_32(8) /*< Don't import the volume ID primary descriptor field. /
707	#define RTFSISOMK_IMPORT_F_NO_VOLUME_SET_ID RT_BIT_32(9) /*< Don't import the volume set ID primary descriptor field. /
708	#define RTFSISOMK_IMPORT_F_NO_PUBLISHER_ID RT_BIT_32(10) /*< Don't import the publisher ID primary descriptor field. /
709	#define RTFSISOMK_IMPORT_F_DATA_PREPARER_ID RT_BIT_32(11) /*< Do import the data preparer ID primary descriptor field. /
710	#define RTFSISOMK_IMPORT_F_APPLICATION_ID RT_BIT_32(12) /*< Do import the application ID primary descriptor field. /
711	#define RTFSISOMK_IMPORT_F_NO_COPYRIGHT_FID RT_BIT_32(13) /*< Don't import the copyright file ID primary descriptor field. /
712	#define RTFSISOMK_IMPORT_F_NO_ABSTRACT_FID RT_BIT_32(14) /*< Don't import the abstract file ID primary descriptor field. /
713	#define RTFSISOMK_IMPORT_F_NO_BIBLIO_FID RT_BIT_32(15) /*< Don't import the bibliographic file ID primary descriptor field. /
714
715	#define RTFSISOMK_IMPORT_F_NO_J_SYSTEM_ID RT_BIT_32(16) /*< Don't import the system ID joliet descriptor field. /
716	#define RTFSISOMK_IMPORT_F_NO_J_VOLUME_ID RT_BIT_32(17) /*< Don't import the volume ID joliet descriptor field. /
717	#define RTFSISOMK_IMPORT_F_NO_J_VOLUME_SET_ID RT_BIT_32(18) /*< Don't import the volume set ID joliet descriptor field. /
718	#define RTFSISOMK_IMPORT_F_NO_J_PUBLISHER_ID RT_BIT_32(19) /*< Don't import the publisher ID joliet descriptor field. /
719	#define RTFSISOMK_IMPORT_F_J_DATA_PREPARER_ID RT_BIT_32(20) /*< Do import the data preparer ID joliet descriptor field. /
720	#define RTFSISOMK_IMPORT_F_J_APPLICATION_ID RT_BIT_32(21) /*< Do import the application ID joliet descriptor field. /
721	#define RTFSISOMK_IMPORT_F_NO_J_COPYRIGHT_FID RT_BIT_32(22) /*< Don't import the copyright file ID joliet descriptor field. /
722	#define RTFSISOMK_IMPORT_F_NO_J_ABSTRACT_FID RT_BIT_32(23) /*< Don't import the abstract file ID joliet descriptor field. /
723	#define RTFSISOMK_IMPORT_F_NO_J_BIBLIO_FID RT_BIT_32(24) /*< Don't import the bibliographic file ID joliet descriptor field. /
724
725	#define RTFSISOMK_IMPORT_F_VALID_MASK UINT32_C(0x01ffffff)
726	/** @} */
727
728
729	/**
730	* Finalizes the image.
731	*
732	* @returns IPRT status code.
733	* @param hIsoMaker The ISO maker handle.
734	*/
735	RTDECL(int) RTFsIsoMakerFinalize(RTFSISOMAKER hIsoMaker);
736
737	/**
738	* Creates a VFS file for a finalized ISO maker instanced.
739	*
740	* The file can be used to access the image. Both sequential and random access
741	* are supported, so that this could in theory be hooked up to a CD/DVD-ROM
742	* drive emulation and used as a virtual ISO image.
743	*
744	* @returns IRPT status code.
745	* @param hIsoMaker The ISO maker handle.
746	* @param phVfsFile Where to return the handle.
747	*/
748	RTDECL(int) RTFsIsoMakerCreateVfsOutputFile(RTFSISOMAKER hIsoMaker, PRTVFSFILE phVfsFile);
749
750
751
752	/**
753	* ISO maker command (creates image file on disk).
754	*
755	* @returns IPRT status code
756	* @param cArgs Number of arguments.
757	* @param papszArgs Pointer to argument array.
758	*/
759	RTDECL(RTEXITCODE) RTFsIsoMakerCmd(unsigned cArgs, char **papszArgs);
760
761	/**
762	* Extended ISO maker command.
763	*
764	* This can be used as a ISO maker command that produces a image file, or
765	* alternatively for setting up a virtual ISO in memory.
766	*
767	* @returns IPRT status code
768	* @param cArgs Number of arguments.
769	* @param papszArgs Pointer to argument array.
770	* @param hVfsCwd The current working directory to assume when processing
771	* relative file/dir references. Pass NIL_RTVFSDIR to use
772	* the current CWD of the process.
773	* @param pszCwd Path to @a hVfsCwdDir. Use for error reporting and
774	* optimizing the open file count if possible.
775	* @param phVfsFile Where to return the virtual ISO. Pass NULL to for
776	* normal operation (creates file on disk).
777	* @param pErrInfo Where to return extended error information in the
778	* virtual ISO mode.
779	*/
780	RTDECL(int) RTFsIsoMakerCmdEx(unsigned cArgs, char *papszArgs, RTVFSDIR hVfsCwd, const char pszCwd,
781	PRTVFSFILE phVfsFile, PRTERRINFO pErrInfo);
782
783
784	/** @} */
785
786	RT_C_DECLS_END
787
788	#endif /* !IPRT_INCLUDED_fsisomaker_h */
789

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

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

Download in other formats: