1/*
2 * Library to access the Apple File System (APFS) format
3 *
4 * Copyright (C) 2018-2021, Joachim Metz <joachim.metz@gmail.com>
5 *
6 * Refer to AUTHORS for acknowledgements.
7 *
8 * This program is free software: you can redistribute it and/or modify
9 * it under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation, either version 3 of the License, or
11 * (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
20 */
21
22#if !defined( _LIBFSAPFS_H )
23#define _LIBFSAPFS_H
24
25#include <libfsapfs/codepage.h>
26#include <libfsapfs/definitions.h>
27#include <libfsapfs/error.h>
28#include <libfsapfs/extern.h>
29#include <libfsapfs/features.h>
30#include <libfsapfs/types.h>
31
32#include <stdio.h>
33
34#if defined( LIBFSAPFS_HAVE_BFIO )
35#include <libbfio.h>
36#endif
37
38#if defined( __cplusplus )
39extern "C" {
40#endif
41
42/* -------------------------------------------------------------------------
43 * Support functions
44 * ------------------------------------------------------------------------- */
45
46/* Returns the library version
47 */
48LIBFSAPFS_EXTERN \
49const char *libfsapfs_get_version(
50             void );
51
52/* Returns the access flags for reading
53 */
54LIBFSAPFS_EXTERN \
55int libfsapfs_get_access_flags_read(
56     void );
57
58/* Retrieves the narrow system string codepage
59 * A value of 0 represents no codepage, UTF-8 encoding is used instead
60 * Returns 1 if successful or -1 on error
61 */
62LIBFSAPFS_EXTERN \
63int libfsapfs_get_codepage(
64     int *codepage,
65     libfsapfs_error_t **error );
66
67/* Sets the narrow system string codepage
68 * A value of 0 represents no codepage, UTF-8 encoding is used instead
69 * Returns 1 if successful or -1 on error
70 */
71LIBFSAPFS_EXTERN \
72int libfsapfs_set_codepage(
73     int codepage,
74     libfsapfs_error_t **error );
75
76/* Determines if a file contains an APFS container signature
77 * Returns 1 if true, 0 if not or -1 on error
78 */
79LIBFSAPFS_EXTERN \
80int libfsapfs_check_container_signature(
81     const char *filename,
82     libfsapfs_error_t **error );
83
84/* Determines if a file contains an APFS volume signature
85 * Returns 1 if true, 0 if not or -1 on error
86 */
87LIBFSAPFS_EXTERN \
88int libfsapfs_check_volume_signature(
89     const char *filename,
90     libfsapfs_error_t **error );
91
92#if defined( LIBFSAPFS_HAVE_WIDE_CHARACTER_TYPE )
93
94/* Determines if a file contains an APFS container signature
95 * Returns 1 if true, 0 if not or -1 on error
96 */
97LIBFSAPFS_EXTERN \
98int libfsapfs_check_container_signature_wide(
99     const wchar_t *filename,
100     libfsapfs_error_t **error );
101
102/* Determines if a file contains an APFS volume signature
103 * Returns 1 if true, 0 if not or -1 on error
104 */
105LIBFSAPFS_EXTERN \
106int libfsapfs_check_volume_signature_wide(
107     const wchar_t *filename,
108     libfsapfs_error_t **error );
109
110#endif /* defined( LIBFSAPFS_HAVE_WIDE_CHARACTER_TYPE ) */
111
112#if defined( LIBFSAPFS_HAVE_BFIO )
113
114/* Determines if a file contains an APFS container signature using a Basic File IO (bfio) handle
115 * Returns 1 if true, 0 if not or -1 on error
116 */
117LIBFSAPFS_EXTERN \
118int libfsapfs_check_container_signature_file_io_handle(
119     libbfio_handle_t *file_io_handle,
120     libfsapfs_error_t **error );
121
122/* Determines if a file contains an APFS volume signature using a Basic File IO (bfio) handle
123 * Returns 1 if true, 0 if not or -1 on error
124 */
125LIBFSAPFS_EXTERN \
126int libfsapfs_check_volume_signature_file_io_handle(
127     libbfio_handle_t *file_io_handle,
128     libfsapfs_error_t **error );
129
130#endif /* defined( LIBFSAPFS_HAVE_BFIO ) */
131
132/* -------------------------------------------------------------------------
133 * Notify functions
134 * ------------------------------------------------------------------------- */
135
136/* Sets the verbose notification
137 */
138LIBFSAPFS_EXTERN \
139void libfsapfs_notify_set_verbose(
140      int verbose );
141
142/* Sets the notification stream
143 * Returns 1 if successful or -1 on error
144 */
145LIBFSAPFS_EXTERN \
146int libfsapfs_notify_set_stream(
147     FILE *stream,
148     libfsapfs_error_t **error );
149
150/* Opens the notification stream using a filename
151 * The stream is opened in append mode
152 * Returns 1 if successful or -1 on error
153 */
154LIBFSAPFS_EXTERN \
155int libfsapfs_notify_stream_open(
156     const char *filename,
157     libfsapfs_error_t **error );
158
159/* Closes the notification stream if opened using a filename
160 * Returns 0 if successful or -1 on error
161 */
162LIBFSAPFS_EXTERN \
163int libfsapfs_notify_stream_close(
164     libfsapfs_error_t **error );
165
166/* -------------------------------------------------------------------------
167 * Error functions
168 * ------------------------------------------------------------------------- */
169
170/* Frees an error
171 */
172LIBFSAPFS_EXTERN \
173void libfsapfs_error_free(
174      libfsapfs_error_t **error );
175
176/* Prints a descriptive string of the error to the stream
177 * Returns the number of printed characters if successful or -1 on error
178 */
179LIBFSAPFS_EXTERN \
180int libfsapfs_error_fprint(
181     libfsapfs_error_t *error,
182     FILE *stream );
183
184/* Prints a descriptive string of the error to the string
185 * The end-of-string character is not included in the return value
186 * Returns the number of printed characters if successful or -1 on error
187 */
188LIBFSAPFS_EXTERN \
189int libfsapfs_error_sprint(
190     libfsapfs_error_t *error,
191     char *string,
192     size_t size );
193
194/* Prints a backtrace of the error to the stream
195 * Returns the number of printed characters if successful or -1 on error
196 */
197LIBFSAPFS_EXTERN \
198int libfsapfs_error_backtrace_fprint(
199     libfsapfs_error_t *error,
200     FILE *stream );
201
202/* Prints a backtrace of the error to the string
203 * The end-of-string character is not included in the return value
204 * Returns the number of printed characters if successful or -1 on error
205 */
206LIBFSAPFS_EXTERN \
207int libfsapfs_error_backtrace_sprint(
208     libfsapfs_error_t *error,
209     char *string,
210     size_t size );
211
212/* -------------------------------------------------------------------------
213 * Container functions
214 * ------------------------------------------------------------------------- */
215
216/* Creates a container
217 * Make sure the value container is referencing, is set to NULL
218 * Returns 1 if successful or -1 on error
219 */
220LIBFSAPFS_EXTERN \
221int libfsapfs_container_initialize(
222     libfsapfs_container_t **container,
223     libfsapfs_error_t **error );
224
225/* Frees a container
226 * Returns 1 if successful or -1 on error
227 */
228LIBFSAPFS_EXTERN \
229int libfsapfs_container_free(
230     libfsapfs_container_t **container,
231     libfsapfs_error_t **error );
232
233/* Signals the container to abort its current activity
234 * Returns 1 if successful or -1 on error
235 */
236LIBFSAPFS_EXTERN \
237int libfsapfs_container_signal_abort(
238     libfsapfs_container_t *container,
239     libfsapfs_error_t **error );
240
241/* Opens a container
242 * Returns 1 if successful or -1 on error
243 */
244LIBFSAPFS_EXTERN \
245int libfsapfs_container_open(
246     libfsapfs_container_t *container,
247     const char *filename,
248     int access_flags,
249     libfsapfs_error_t **error );
250
251#if defined( LIBFSAPFS_HAVE_WIDE_CHARACTER_TYPE )
252
253/* Opens a container
254 * Returns 1 if successful or -1 on error
255 */
256LIBFSAPFS_EXTERN \
257int libfsapfs_container_open_wide(
258     libfsapfs_container_t *container,
259     const wchar_t *filename,
260     int access_flags,
261     libfsapfs_error_t **error );
262
263#endif /* defined( LIBFSAPFS_HAVE_WIDE_CHARACTER_TYPE ) */
264
265#if defined( LIBFSAPFS_HAVE_BFIO )
266
267/* Opens a container using a Basic File IO (bfio) handle
268 * Returns 1 if successful or -1 on error
269 */
270LIBFSAPFS_EXTERN \
271int libfsapfs_container_open_file_io_handle(
272     libfsapfs_container_t *container,
273     libbfio_handle_t *file_io_handle,
274     int access_flags,
275     libfsapfs_error_t **error );
276
277#endif /* defined( LIBFSAPFS_HAVE_BFIO ) */
278
279/* Closes a container
280 * Returns 0 if successful or -1 on error
281 */
282LIBFSAPFS_EXTERN \
283int libfsapfs_container_close(
284     libfsapfs_container_t *container,
285     libfsapfs_error_t **error );
286
287/* Retrieves the size
288 * Returns 1 if successful or -1 on error
289 */
290LIBFSAPFS_EXTERN \
291int libfsapfs_container_get_size(
292     libfsapfs_container_t *container,
293     size64_t *size,
294     libfsapfs_error_t **error );
295
296/* Retrieves the identifier
297 * The identifier is an UUID stored in big-endian and is 16 bytes of size
298 * Returns 1 if successful or -1 on error
299 */
300LIBFSAPFS_EXTERN \
301int libfsapfs_container_get_identifier(
302     libfsapfs_container_t *container,
303     uint8_t *uuid_data,
304     size_t uuid_data_size,
305     libfsapfs_error_t **error );
306
307/* Determines if the container is locked
308 * Returns 1 if locked, 0 if not or -1 on error
309 */
310LIBFSAPFS_EXTERN \
311int libfsapfs_container_is_locked(
312     libfsapfs_container_t *container,
313     libfsapfs_error_t **error );
314
315/* Retrieves the number of volumes
316 * Returns 1 if successful or -1 on error
317 */
318LIBFSAPFS_EXTERN \
319int libfsapfs_container_get_number_of_volumes(
320     libfsapfs_container_t *container,
321     int *number_of_volumes,
322     libfsapfs_error_t **error );
323
324/* Retrieves a specific of volume
325 * The volume reference must be freed after use with libfsapfs_volume_free
326 * Returns 1 if successful or -1 on error
327 */
328LIBFSAPFS_EXTERN \
329int libfsapfs_container_get_volume_by_index(
330     libfsapfs_container_t *container,
331     int volume_index,
332     libfsapfs_volume_t **volume,
333     libfsapfs_error_t **error );
334
335/* -------------------------------------------------------------------------
336 * Volume functions
337 * ------------------------------------------------------------------------- */
338
339/* Frees a volume
340 * Returns 1 if successful or -1 on error
341 */
342LIBFSAPFS_EXTERN \
343int libfsapfs_volume_free(
344     libfsapfs_volume_t **volume,
345     libfsapfs_error_t **error );
346
347/* Unlocks the volume
348 * Returns 1 if the volume is unlocked, 0 if not or -1 on error
349 */
350LIBFSAPFS_EXTERN \
351int libfsapfs_volume_unlock(
352     libfsapfs_volume_t *volume,
353     libfsapfs_error_t **error );
354
355/* Retrieves the feature flags
356 * Returns 1 if successful or -1 on error
357 */
358LIBFSAPFS_EXTERN \
359int libfsapfs_volume_get_features_flags(
360     libfsapfs_volume_t *volume,
361     uint64_t *compatible_features_flags,
362     uint64_t *incompatible_features_flags,
363     uint64_t *read_only_compatible_features_flags,
364     libfsapfs_error_t **error );
365
366/* Retrieves the size
367 * Returns 1 if successful or -1 on error
368 */
369LIBFSAPFS_EXTERN \
370int libfsapfs_volume_get_size(
371     libfsapfs_volume_t *volume,
372     size64_t *size,
373     libfsapfs_error_t **error );
374
375/* Retrieves the identifier
376 * The identifier is an UUID stored in big-endian and is 16 bytes of size
377 * Returns 1 if successful or -1 on error
378 */
379LIBFSAPFS_EXTERN \
380int libfsapfs_volume_get_identifier(
381     libfsapfs_volume_t *volume,
382     uint8_t *uuid_data,
383     size_t uuid_data_size,
384     libfsapfs_error_t **error );
385
386/* Retrieves the size of the UTF-8 encoded name
387 * The returned size includes the end of string character
388 * Returns 1 if successful or -1 on error
389 */
390LIBFSAPFS_EXTERN \
391int libfsapfs_volume_get_utf8_name_size(
392     libfsapfs_volume_t *volume,
393     size_t *utf8_string_size,
394     libfsapfs_error_t **error );
395
396/* Retrieves the UTF-8 encoded name
397 * The size should include the end of string character
398 * Returns 1 if successful or -1 on error
399 */
400LIBFSAPFS_EXTERN \
401int libfsapfs_volume_get_utf8_name(
402     libfsapfs_volume_t *volume,
403     uint8_t *utf8_string,
404     size_t utf8_string_size,
405     libfsapfs_error_t **error );
406
407/* Retrieves the size of the UTF-16 encoded name
408 * The returned size includes the end of string character
409 * Returns 1 if successful or -1 on error
410 */
411LIBFSAPFS_EXTERN \
412int libfsapfs_volume_get_utf16_name_size(
413     libfsapfs_volume_t *volume,
414     size_t *utf16_string_size,
415     libfsapfs_error_t **error );
416
417/* Retrieves the UTF-16 encoded name
418 * The size should include the end of string character
419 * Returns 1 if successful or -1 on error
420 */
421LIBFSAPFS_EXTERN \
422int libfsapfs_volume_get_utf16_name(
423     libfsapfs_volume_t *volume,
424     uint16_t *utf16_string,
425     size_t utf16_string_size,
426     libfsapfs_error_t **error );
427
428/* Determines if the volume is locked
429 * Returns 1 if locked, 0 if not or -1 on error
430 */
431LIBFSAPFS_EXTERN \
432int libfsapfs_volume_is_locked(
433     libfsapfs_volume_t *volume,
434     libfsapfs_error_t **error );
435
436/* Sets an UTF-8 formatted password
437 * This function needs to be used before one of the open or unlock functions
438 * Returns 1 if successful, 0 if password is invalid or -1 on error
439 */
440LIBFSAPFS_EXTERN \
441int libfsapfs_volume_set_utf8_password(
442     libfsapfs_volume_t *volume,
443     const uint8_t *utf8_string,
444     size_t utf8_string_length,
445     libfsapfs_error_t **error );
446
447/* Sets an UTF-16 formatted password
448 * This function needs to be used before one of the open or unlock functions
449 * Returns 1 if successful, 0 if password is invalid or -1 on error
450 */
451LIBFSAPFS_EXTERN \
452int libfsapfs_volume_set_utf16_password(
453     libfsapfs_volume_t *volume,
454     const uint16_t *utf16_string,
455     size_t utf16_string_length,
456     libfsapfs_error_t **error );
457
458/* Sets an UTF-8 formatted recovery password
459 * This function needs to be used before one of the open or unlock functions
460 * Returns 1 if successful, 0 if recovery password is invalid or -1 on error
461 */
462LIBFSAPFS_EXTERN \
463int libfsapfs_volume_set_utf8_recovery_password(
464     libfsapfs_volume_t *volume,
465     const uint8_t *utf8_string,
466     size_t utf8_string_length,
467     libfsapfs_error_t **error );
468
469/* Sets an UTF-16 formatted recovery password
470 * This function needs to be used before one of the open or unlock functions
471 * Returns 1 if successful, 0 if recovery password is invalid or -1 on error
472 */
473LIBFSAPFS_EXTERN \
474int libfsapfs_volume_set_utf16_recovery_password(
475     libfsapfs_volume_t *volume,
476     const uint16_t *utf16_string,
477     size_t utf16_string_length,
478     libfsapfs_error_t **error );
479
480/* Retrieves the next file entry identifier
481 * Returns 1 if successful or -1 on error
482 */
483LIBFSAPFS_EXTERN \
484int libfsapfs_volume_get_next_file_entry_identifier(
485     libfsapfs_volume_t *volume,
486     uint64_t *identifier,
487     libfsapfs_error_t **error );
488
489/* Retrieves the file entry for a specific identifier
490 * Returns 1 if successful, 0 if not available or -1 on error
491 */
492LIBFSAPFS_EXTERN \
493int libfsapfs_volume_get_file_entry_by_identifier(
494     libfsapfs_volume_t *volume,
495     uint64_t identifier,
496     libfsapfs_file_entry_t **file_entry,
497     libfsapfs_error_t **error );
498
499/* Retrieves the root directory file entry
500 * Returns 1 if successful or -1 on error
501 */
502LIBFSAPFS_EXTERN \
503int libfsapfs_volume_get_root_directory(
504     libfsapfs_volume_t *volume,
505     libfsapfs_file_entry_t **file_entry,
506     libfsapfs_error_t **error );
507
508/* Retrieves the file entry for an UTF-8 encoded path
509 * Returns 1 if successful, 0 if no such file entry or -1 on error
510 */
511LIBFSAPFS_EXTERN \
512int libfsapfs_volume_get_file_entry_by_utf8_path(
513     libfsapfs_volume_t *volume,
514     const uint8_t *utf8_string,
515     size_t utf8_string_length,
516     libfsapfs_file_entry_t **file_entry,
517     libfsapfs_error_t **error );
518
519/* Retrieves the file entry for an UTF-16 encoded path
520 * Returns 1 if successful, 0 if no such file entry or -1 on error
521 */
522LIBFSAPFS_EXTERN \
523int libfsapfs_volume_get_file_entry_by_utf16_path(
524     libfsapfs_volume_t *volume,
525     const uint16_t *utf16_string,
526     size_t utf16_string_length,
527     libfsapfs_file_entry_t **file_entry,
528     libfsapfs_error_t **error );
529
530/* Retrieves the number of snapshots
531 * Returns 1 if successful or -1 on error
532 */
533LIBFSAPFS_EXTERN \
534int libfsapfs_volume_get_number_of_snapshots(
535     libfsapfs_volume_t *volume,
536     int *number_of_snapshots,
537     libfsapfs_error_t **error );
538
539/* Retrieves a specific of snapshot
540 * The snapshot reference must be freed after use with libfsapfs_snapshot_free
541 * Returns 1 if successful or -1 on error
542 */
543LIBFSAPFS_EXTERN \
544int libfsapfs_volume_get_snapshot_by_index(
545     libfsapfs_volume_t *volume,
546     int snapshot_index,
547     libfsapfs_snapshot_t **snapshot,
548     libfsapfs_error_t **error );
549
550/* -------------------------------------------------------------------------
551 * Snapshot functions
552 * ------------------------------------------------------------------------- */
553
554/* Frees a snapshot
555 * Returns 1 if successful or -1 on error
556 */
557LIBFSAPFS_EXTERN \
558int libfsapfs_snapshot_free(
559     libfsapfs_snapshot_t **snapshot,
560     libfsapfs_error_t **error );
561
562/* Retrieves the size of the UTF-8 encoded name
563 * The returned size includes the end of string character
564 * Returns 1 if successful or -1 on error
565 */
566LIBFSAPFS_EXTERN \
567int libfsapfs_snapshot_get_utf8_name_size(
568     libfsapfs_snapshot_t *snapshot,
569     size_t *utf8_string_size,
570     libfsapfs_error_t **error );
571
572/* Retrieves the UTF-8 encoded name
573 * The size should include the end of string character
574 * Returns 1 if successful or -1 on error
575 */
576LIBFSAPFS_EXTERN \
577int libfsapfs_snapshot_get_utf8_name(
578     libfsapfs_snapshot_t *snapshot,
579     uint8_t *utf8_string,
580     size_t utf8_string_size,
581     libfsapfs_error_t **error );
582
583/* Retrieves the size of the UTF-16 encoded name
584 * The returned size includes the end of string character
585 * Returns 1 if successful or -1 on error
586 */
587LIBFSAPFS_EXTERN \
588int libfsapfs_snapshot_get_utf16_name_size(
589     libfsapfs_snapshot_t *snapshot,
590     size_t *utf16_string_size,
591     libfsapfs_error_t **error );
592
593/* Retrieves the UTF-16 encoded name
594 * The size should include the end of string character
595 * Returns 1 if successful or -1 on error
596 */
597LIBFSAPFS_EXTERN \
598int libfsapfs_snapshot_get_utf16_name(
599     libfsapfs_snapshot_t *snapshot,
600     uint16_t *utf16_string,
601     size_t utf16_string_size,
602     libfsapfs_error_t **error );
603
604/* -------------------------------------------------------------------------
605 * File entry functions
606 * ------------------------------------------------------------------------- */
607
608/* Frees a file entry
609 * Returns 1 if successful or -1 on error
610 */
611LIBFSAPFS_EXTERN \
612int libfsapfs_file_entry_free(
613     libfsapfs_file_entry_t **file_entry,
614     libfsapfs_error_t **error );
615
616/* Retrieves the identifier (or inode number)
617 * This value is retrieved from the inode
618 * Returns 1 if successful or -1 on error
619 */
620LIBFSAPFS_EXTERN \
621int libfsapfs_file_entry_get_identifier(
622     libfsapfs_file_entry_t *file_entry,
623     uint64_t *identifier,
624     libfsapfs_error_t **error );
625
626/* Retrieves the parent identifier (or inode number)
627 * This value is retrieved from the inode
628 * Returns 1 if successful or -1 on error
629 */
630LIBFSAPFS_EXTERN \
631int libfsapfs_file_entry_get_parent_identifier(
632     libfsapfs_file_entry_t *file_entry,
633     uint64_t *parent_identifier,
634     libfsapfs_error_t **error );
635
636/* Retrieves the parent file entry
637 * Returns 1 if successful, 0 if no such file entry or -1 on error
638 */
639LIBFSAPFS_EXTERN \
640int libfsapfs_file_entry_get_parent_file_entry(
641     libfsapfs_file_entry_t *file_entry,
642     libfsapfs_file_entry_t **parent_file_entry,
643     libfsapfs_error_t **error );
644
645/* Retrieves the creation date and time
646 * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
647 * This value is retrieved from the inode
648 * Returns 1 if successful or -1 on error
649 */
650LIBFSAPFS_EXTERN \
651int libfsapfs_file_entry_get_creation_time(
652     libfsapfs_file_entry_t *file_entry,
653     int64_t *posix_time,
654     libfsapfs_error_t **error );
655
656/* Retrieves the modification date and time
657 * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
658 * This value is retrieved from the inode
659 * Returns 1 if successful or -1 on error
660 */
661LIBFSAPFS_EXTERN \
662int libfsapfs_file_entry_get_modification_time(
663     libfsapfs_file_entry_t *file_entry,
664     int64_t *posix_time,
665     libfsapfs_error_t **error );
666
667/* Retrieves the access date and time
668 * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
669 * This value is retrieved from the inode
670 * Returns 1 if successful or -1 on error
671 */
672LIBFSAPFS_EXTERN \
673int libfsapfs_file_entry_get_access_time(
674     libfsapfs_file_entry_t *file_entry,
675     int64_t *posix_time,
676     libfsapfs_error_t **error );
677
678/* Retrieves the inode change date and time
679 * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
680 * This value is retrieved from the inode
681 * Returns 1 if successful or -1 on error
682 */
683LIBFSAPFS_EXTERN \
684int libfsapfs_file_entry_get_inode_change_time(
685     libfsapfs_file_entry_t *file_entry,
686     int64_t *posix_time,
687     libfsapfs_error_t **error );
688
689/* Retrieves the added date and time
690 * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
691 * This value is retrieved from the directory record
692 * Returns 1 if successful, 0 if not available or -1 on error
693 */
694LIBFSAPFS_EXTERN \
695int libfsapfs_file_entry_get_added_time(
696     libfsapfs_file_entry_t *file_entry,
697     int64_t *posix_time,
698     libfsapfs_error_t **error );
699
700/* Retrieves the user identifier
701 * This value is retrieved from the inode
702 * Returns 1 if successful or -1 on error
703 */
704LIBFSAPFS_EXTERN \
705int libfsapfs_file_entry_get_owner_identifier(
706     libfsapfs_file_entry_t *file_entry,
707     uint32_t *owner_identifier,
708     libfsapfs_error_t **error );
709
710/* Retrieves the group identifier
711 * This value is retrieved from the inode
712 * Returns 1 if successful or -1 on error
713 */
714LIBFSAPFS_EXTERN \
715int libfsapfs_file_entry_get_group_identifier(
716     libfsapfs_file_entry_t *file_entry,
717     uint32_t *group_identifier,
718     libfsapfs_error_t **error );
719
720/* Retrieves the file mode
721 * This value is retrieved from the inode
722 * Returns 1 if successful or -1 on error
723 */
724LIBFSAPFS_EXTERN \
725int libfsapfs_file_entry_get_file_mode(
726     libfsapfs_file_entry_t *file_entry,
727     uint16_t *file_mode,
728     libfsapfs_error_t **error );
729
730/* Retrieves the size of the UTF-8 encoded name
731 * The returned size includes the end of string character
732 * Returns 1 if successful or -1 on error
733 */
734LIBFSAPFS_EXTERN \
735int libfsapfs_file_entry_get_utf8_name_size(
736     libfsapfs_file_entry_t *file_entry,
737     size_t *utf8_string_size,
738     libfsapfs_error_t **error );
739
740/* Retrieves the UTF-8 encoded name
741 * The size should include the end of string character
742 * This value is retrieved from the inode
743 * Returns 1 if successful or -1 on error
744 */
745LIBFSAPFS_EXTERN \
746int libfsapfs_file_entry_get_utf8_name(
747     libfsapfs_file_entry_t *file_entry,
748     uint8_t *utf8_string,
749     size_t utf8_string_size,
750     libfsapfs_error_t **error );
751
752/* Retrieves the size of the UTF-16 encoded name
753 * The returned size includes the end of string character
754 * This value is retrieved from the inode
755 * Returns 1 if successful or -1 on error
756 */
757LIBFSAPFS_EXTERN \
758int libfsapfs_file_entry_get_utf16_name_size(
759     libfsapfs_file_entry_t *file_entry,
760     size_t *utf16_string_size,
761     libfsapfs_error_t **error );
762
763/* Retrieves the UTF-16 encoded name
764 * The size should include the end of string character
765 * This value is retrieved from the inode
766 * Returns 1 if successful or -1 on error
767 */
768LIBFSAPFS_EXTERN \
769int libfsapfs_file_entry_get_utf16_name(
770     libfsapfs_file_entry_t *file_entry,
771     uint16_t *utf16_string,
772     size_t utf16_string_size,
773     libfsapfs_error_t **error );
774
775/* Retrieves the size of the UTF-8 encoded symbolic link target
776 * The size should include the end of string character
777 * This value is retrieved from the com.apple.fs.symlink extended attribute
778 * Returns 1 if successful, 0 if not available or -1 on error
779 */
780LIBFSAPFS_EXTERN \
781int libfsapfs_file_entry_get_utf8_symbolic_link_target_size(
782     libfsapfs_file_entry_t *file_entry,
783     size_t *utf8_string_size,
784     libfsapfs_error_t **error );
785
786/* Retrieves the UTF-8 encoded symbolic link target
787 * The size should include the end of string character
788 * This value is retrieved from the com.apple.fs.symlink extended attribute
789 * Returns 1 if successful, 0 if not available or -1 on error
790 */
791LIBFSAPFS_EXTERN \
792int libfsapfs_file_entry_get_utf8_symbolic_link_target(
793     libfsapfs_file_entry_t *file_entry,
794     uint8_t *utf8_string,
795     size_t utf8_string_size,
796     libfsapfs_error_t **error );
797
798/* Retrieves the size of the UTF-16 encoded symbolic link target
799 * The size should include the end of string character
800 * This value is retrieved from the com.apple.fs.symlink extended attribute
801 * Returns 1 if successful, 0 if not available or -1 on error
802 */
803LIBFSAPFS_EXTERN \
804int libfsapfs_file_entry_get_utf16_symbolic_link_target_size(
805     libfsapfs_file_entry_t *file_entry,
806     size_t *utf16_string_size,
807     libfsapfs_error_t **error );
808
809/* Retrieves the UTF-16 encoded symbolic link target
810 * The size should include the end of string character
811 * This value is retrieved from the com.apple.fs.symlink extended attribute
812 * Returns 1 if successful, 0 if not available or -1 on error
813 */
814LIBFSAPFS_EXTERN \
815int libfsapfs_file_entry_get_utf16_symbolic_link_target(
816     libfsapfs_file_entry_t *file_entry,
817     uint16_t *utf16_string,
818     size_t utf16_string_size,
819     libfsapfs_error_t **error );
820
821/* Retrieves the number of extended attributes
822 * Returns 1 if successful or -1 on error
823 */
824LIBFSAPFS_EXTERN \
825int libfsapfs_file_entry_get_number_of_extended_attributes(
826     libfsapfs_file_entry_t *file_entry,
827     int *number_of_extended_attributes,
828     libfsapfs_error_t **error );
829
830/* Retrieves the extended attribute for the specific index
831 * Returns 1 if successful or -1 on error
832 */
833LIBFSAPFS_EXTERN \
834int libfsapfs_file_entry_get_extended_attribute_by_index(
835     libfsapfs_file_entry_t *file_entry,
836     int extended_attribute_index,
837     libfsapfs_extended_attribute_t **extended_attribute,
838     libfsapfs_error_t **error );
839
840/* Determines if there is an extended attribute for an UTF-8 encoded name
841 * Returns 1 if available, 0 if not or -1 on error
842 */
843LIBFSAPFS_EXTERN \
844int libfsapfs_file_entry_has_extended_attribute_by_utf8_name(
845     libfsapfs_file_entry_t *file_entry,
846     const uint8_t *utf8_string,
847     size_t utf8_string_length,
848     libfsapfs_error_t **error );
849
850/* Determines if there is an extended attribute for an UTF-16 encoded name
851 * Returns 1 if available, 0 if not or -1 on error
852 */
853LIBFSAPFS_EXTERN \
854int libfsapfs_file_entry_has_extended_attribute_by_utf16_name(
855     libfsapfs_file_entry_t *file_entry,
856     const uint16_t *utf16_string,
857     size_t utf16_string_length,
858     libfsapfs_error_t **error );
859
860/* Retrieves the extended attribute for an UTF-8 encoded name
861 * Returns 1 if successful, 0 if the file entry does not contain such value or -1 on error
862 */
863LIBFSAPFS_EXTERN \
864int libfsapfs_file_entry_get_extended_attribute_by_utf8_name(
865     libfsapfs_file_entry_t *file_entry,
866     const uint8_t *utf8_string,
867     size_t utf8_string_length,
868     libfsapfs_extended_attribute_t **extended_attribute,
869     libfsapfs_error_t **error );
870
871/* Retrieves the extended attribute for an UTF-16 encoded name
872 * Returns 1 if successful, 0 if the file entry does not contain such value or -1 on error
873 */
874LIBFSAPFS_EXTERN \
875int libfsapfs_file_entry_get_extended_attribute_by_utf16_name(
876     libfsapfs_file_entry_t *file_entry,
877     const uint16_t *utf16_string,
878     size_t utf16_string_length,
879     libfsapfs_extended_attribute_t **extended_attribute,
880     libfsapfs_error_t **error );
881
882/* Retrieves the number of sub file entries
883 * Returns 1 if successful or -1 on error
884 */
885LIBFSAPFS_EXTERN \
886int libfsapfs_file_entry_get_number_of_sub_file_entries(
887     libfsapfs_file_entry_t *file_entry,
888     int *number_of_sub_file_entries,
889     libfsapfs_error_t **error );
890
891/* Retrieves the sub file entry for the specific index
892 * Returns 1 if successful or -1 on error
893 */
894LIBFSAPFS_EXTERN \
895int libfsapfs_file_entry_get_sub_file_entry_by_index(
896     libfsapfs_file_entry_t *file_entry,
897     int sub_file_entry_index,
898     libfsapfs_file_entry_t **sub_file_entry,
899     libfsapfs_error_t **error );
900
901/* Retrieves the sub file entry for an UTF-8 encoded name
902 * Returns 1 if successful, 0 if the file entry does not contain such value or -1 on error
903 */
904LIBFSAPFS_EXTERN \
905int libfsapfs_file_entry_get_sub_file_entry_by_utf8_name(
906     libfsapfs_file_entry_t *file_entry,
907     const uint8_t *utf8_string,
908     size_t utf8_string_length,
909     libfsapfs_file_entry_t **sub_file_entry,
910     libfsapfs_error_t **error );
911
912/* Retrieves the sub file entry for an UTF-16 encoded name
913 * Returns 1 if successful, 0 if the file entry does not contain such value or -1 on error
914 */
915LIBFSAPFS_EXTERN \
916int libfsapfs_file_entry_get_sub_file_entry_by_utf16_name(
917     libfsapfs_file_entry_t *file_entry,
918     const uint16_t *utf16_string,
919     size_t utf16_string_length,
920     libfsapfs_file_entry_t **sub_file_entry,
921     libfsapfs_error_t **error );
922
923/* Reads data at the current offset
924 * Returns the number of bytes read or -1 on error
925 */
926LIBFSAPFS_EXTERN \
927ssize_t libfsapfs_file_entry_read_buffer(
928         libfsapfs_file_entry_t *file_entry,
929         void *buffer,
930         size_t buffer_size,
931         libfsapfs_error_t **error );
932
933/* Reads data at a specific offset
934 * Returns the number of bytes read or -1 on error
935 */
936LIBFSAPFS_EXTERN \
937ssize_t libfsapfs_file_entry_read_buffer_at_offset(
938         libfsapfs_file_entry_t *file_entry,
939         void *buffer,
940         size_t buffer_size,
941         off64_t offset,
942         libfsapfs_error_t **error );
943
944/* Seeks a certain offset
945 * Returns the offset if seek is successful or -1 on error
946 */
947LIBFSAPFS_EXTERN \
948off64_t libfsapfs_file_entry_seek_offset(
949         libfsapfs_file_entry_t *file_entry,
950         off64_t offset,
951         int whence,
952         libfsapfs_error_t **error );
953
954/* Retrieves the current offset
955 * Returns the offset if successful or -1 on error
956 */
957LIBFSAPFS_EXTERN \
958int libfsapfs_file_entry_get_offset(
959     libfsapfs_file_entry_t *file_entry,
960     off64_t *offset,
961     libfsapfs_error_t **error );
962
963/* Retrieves the size
964 * Returns 1 if successful or -1 on error
965 */
966LIBFSAPFS_EXTERN \
967int libfsapfs_file_entry_get_size(
968     libfsapfs_file_entry_t *file_entry,
969     size64_t *size,
970     libfsapfs_error_t **error );
971
972/* Retrieves the number of extents
973 * Returns 1 if successful or -1 on error
974 */
975LIBFSAPFS_EXTERN \
976int libfsapfs_file_entry_get_number_of_extents(
977     libfsapfs_file_entry_t *file_entry,
978     int *number_of_extents,
979     libfsapfs_error_t **error );
980
981/* Retrieves a specific extent
982 * Returns 1 if successful or -1 on error
983 */
984LIBFSAPFS_EXTERN \
985int libfsapfs_file_entry_get_extent_by_index(
986     libfsapfs_file_entry_t *file_entry,
987     int extent_index,
988     off64_t *extent_offset,
989     size64_t *extent_size,
990     uint32_t *extent_flags,
991     libfsapfs_error_t **error );
992
993/* -------------------------------------------------------------------------
994 * Extended attribute functions
995 * ------------------------------------------------------------------------- */
996
997/* Frees an extended attribute
998 * Returns 1 if successful or -1 on error
999 */
1000LIBFSAPFS_EXTERN \
1001int libfsapfs_extended_attribute_free(
1002     libfsapfs_extended_attribute_t **extended_attribute,
1003     libfsapfs_error_t **error );
1004
1005/* Retrieves the identifier
1006 * Returns 1 if successful or -1 on error
1007 */
1008LIBFSAPFS_EXTERN \
1009int libfsapfs_extended_attribute_get_identifier(
1010     libfsapfs_extended_attribute_t *extended_attribute,
1011     uint64_t *identifier,
1012     libfsapfs_error_t **error );
1013
1014/* Retrieves the size of the UTF-8 encoded name
1015 * The returned size includes the end of string character
1016 * Returns 1 if successful or -1 on error
1017 */
1018LIBFSAPFS_EXTERN \
1019int libfsapfs_extended_attribute_get_utf8_name_size(
1020     libfsapfs_extended_attribute_t *extended_attribute,
1021     size_t *utf8_string_size,
1022     libfsapfs_error_t **error );
1023
1024/* Retrieves the UTF-8 encoded name
1025 * The size should include the end of string character
1026 * Returns 1 if successful or -1 on error
1027 */
1028LIBFSAPFS_EXTERN \
1029int libfsapfs_extended_attribute_get_utf8_name(
1030     libfsapfs_extended_attribute_t *extended_attribute,
1031     uint8_t *utf8_string,
1032     size_t utf8_string_size,
1033     libfsapfs_error_t **error );
1034
1035/* Retrieves the size of the UTF-16 encoded name
1036 * The returned size includes the end of string character
1037 * Returns 1 if successful or -1 on error
1038 */
1039LIBFSAPFS_EXTERN \
1040int libfsapfs_extended_attribute_get_utf16_name_size(
1041     libfsapfs_extended_attribute_t *extended_attribute,
1042     size_t *utf16_string_size,
1043     libfsapfs_error_t **error );
1044
1045/* Retrieves the UTF-16 encoded name
1046 * The size should include the end of string character
1047 * Returns 1 if successful or -1 on error
1048 */
1049LIBFSAPFS_EXTERN \
1050int libfsapfs_extended_attribute_get_utf16_name(
1051     libfsapfs_extended_attribute_t *extended_attribute,
1052     uint16_t *utf16_string,
1053     size_t utf16_string_size,
1054     libfsapfs_error_t **error );
1055
1056/* Reads data at the current offset into a buffer
1057 * Returns the number of bytes read or -1 on error
1058 */
1059LIBFSAPFS_EXTERN \
1060ssize_t libfsapfs_extended_attribute_read_buffer(
1061         libfsapfs_extended_attribute_t *extended_attribute,
1062         void *buffer,
1063         size_t buffer_size,
1064         libfsapfs_error_t **error );
1065
1066/* Reads data at a specific offset
1067 * Returns the number of bytes read or -1 on error
1068 */
1069LIBFSAPFS_EXTERN \
1070ssize_t libfsapfs_extended_attribute_read_buffer_at_offset(
1071         libfsapfs_extended_attribute_t *extended_attribute,
1072         void *buffer,
1073         size_t buffer_size,
1074         off64_t offset,
1075         libfsapfs_error_t **error );
1076
1077/* Seeks a certain offset
1078 * Returns the offset if seek is successful or -1 on error
1079 */
1080LIBFSAPFS_EXTERN \
1081off64_t libfsapfs_extended_attribute_seek_offset(
1082         libfsapfs_extended_attribute_t *extended_attribute,
1083         off64_t offset,
1084         int whence,
1085         libfsapfs_error_t **error );
1086
1087/* Retrieves the current offset
1088 * Returns the offset if successful or -1 on error
1089 */
1090LIBFSAPFS_EXTERN \
1091int libfsapfs_extended_attribute_get_offset(
1092     libfsapfs_extended_attribute_t *extended_attribute,
1093     off64_t *offset,
1094     libfsapfs_error_t **error );
1095
1096/* Retrieves the size of the data stream object
1097 * Returns 1 if successful or -1 on error
1098 */
1099LIBFSAPFS_EXTERN \
1100int libfsapfs_extended_attribute_get_size(
1101     libfsapfs_extended_attribute_t *extended_attribute,
1102     size64_t *size,
1103     libfsapfs_error_t **error );
1104
1105#if defined( __cplusplus )
1106}
1107#endif
1108
1109#endif /* !defined( _LIBFSAPFS_H ) */
1110
1111