[apple/copyfile.git] / xattr_properties.h

/*
 * Copyright (c) 2013 Apple, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

#ifndef _XATTR_PROPERTIES_H
#define _XATTR_PROPERTIES_H

#include <stdint.h>

#include <sys/cdefs.h>
#include <Availability.h>

__BEGIN_DECLS

/*
 * CopyOperationIntent_t is used to declare what the intent of the copy is.
 * Not a bit-field (for now, at least).
 *
 * CopyOperationIntentCopy indicates that the EA is attached to an object
 * that is simply being copied.  E.g., cp src dst
 *
 * CopyOperationIntentSave indicates that the EA is attached to an object
 * being saved; as in a "safe save," the destination is being replaced by
 * the source, so the question is whether the EA should be applied to the
 * destination, or generated anew.
 *
 * CopyOperationIntentShare indicates that the EA is attached to an object that
 * is being given out to other people.  For example, saving to a public folder,
 * or attaching to an email message.
 */

typedef enum {
	CopyOperationIntentCopy = 1,
	CopyOperationIntentSave,
	CopyOperationIntentShare,
} CopyOperationIntent_t;

typedef uint64_t CopyOperationProperties_t;

/*
 * Various properties used to determine how to handle the xattr during
 * copying.  The intent is that the default is reasonable for most xattrs.
 */

/*
 * kCopyOperationPropertyNoExport
 * Declare that the extended property should not be exported; this is
 * deliberately a bit vague, but this is used by CopyOperationIntentShare
 * to indicate not to preserve the xattr.
 */
#define kCopyOperationPropertyNoExport	((CopyOperationProperties_t)0x0001)

/*
 * kCopyOperationPropertyContentDependent
 * Declares the extended attribute to be tied to the contents of the file (or
 * vice versa), such that it should be re-created when the contents of the
 * file change.  Examples might include cryptographic keys, checksums, saved
 * position or search information, and text encoding.
 *
 * This property causes the EA to be preserved for copy and share, but not for
 * safe save.  (In a safe save, the EA exists on the original, and will not
 * be copied to the new version.)
 */
#define	kCopyOperationPropertyContentDependent	((CopyOperationProperties_t)0x0002)

/*
 * kCopyOperationPropertyNeverPreserve
 * Declares that the extended attribute is never to be copied, for any
 * intention type.
 */
#define kCopyOperationPropertyNeverPreserve	((CopyOperationProperties_t)0x0004)

#if 0
/*
 * These are all going to be removed, and I don't believe anyone used them.
 */
/*
 * Given an extended attribute name, and a set of properties, return an
 *  allocated C string with the name.  This will return NULL on error;
 * errno may be set to ENOMEM if the new name cannot be allocated, or
 * ENAMETOOLONG if the new name is longer than the maximum for EAs (127 UTF8
 * characters).  The caller must deallocate the return value otherwise.
 *
 * If no properties are set, it returns a copy of the EA name.
 *
 * If the EA name is in the internal list, and the properties are the same as
 * defined there, then it will also return an unmodified copy of the EA name.
 */
extern char *_xattrNameWithProperties(const char *, CopyOperationProperties_t) DEPRECATED_IN_MAC_OS_X_VERSION_10_10_AND_LATER;

/*
 * Given an extended attribute name, which may or may not have properties encoded
 * as a suffix, return just the name of the attribute.  E.g., com.example.mine#P
 * would return "com.example.mine".  The return value will be NULL on error;
 * errno will be set to ENOMEM if it cannot be allocated.  The caller must deallocate
 * the return value.
 */
extern char *_xattrNameWithoutProperties(const char *) DEPRECATED_IN_MAC_OS_X_VERSION_10_10_AND_LATER;

/*
 * Given an EA name, return the properties.  If the name is in the internal list,
 * those properties will be returned.  Unknown property encodings are ignored.
 */
extern CopyOperationProperties_t _xattrPropertiesFromName(const char *) DEPRECATED_IN_MAC_OS_X_VERSION_10_10_AND_LATER;
#endif /* 0 */

__END_DECLS

#endif /* _XATTR_PROPERTIES_H */
Commit	Line	Data
11f767b3 A	1	/*
	2	* Copyright (c) 2013 Apple, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. Please obtain a copy of the License at
	10	* http://www.opensource.apple.com/apsl/ and read it before using this
	11	* file.
	12	*
	13	* The Original Code and all software distributed under the License are
	14	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	15	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	16	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	17	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	18	* Please see the License for the specific language governing rights and
	19	* limitations under the License.
	20	*
	21	* @APPLE_LICENSE_HEADER_END@
	22	*/
	23
	24	#ifndef _XATTR_PROPERTIES_H
	25	#define _XATTR_PROPERTIES_H
	26
	27	#include <stdint.h>
	28
	29	#include <sys/cdefs.h>
618b37c8	30	#include <Availability.h>
11f767b3 A	31
	32	__BEGIN_DECLS
	33
	34	/*
	35	* CopyOperationIntent_t is used to declare what the intent of the copy is.
	36	* Not a bit-field (for now, at least).
	37	*
	38	* CopyOperationIntentCopy indicates that the EA is attached to an object
	39	* that is simply being copied. E.g., cp src dst
	40	*
	41	* CopyOperationIntentSave indicates that the EA is attached to an object
	42	* being saved; as in a "safe save," the destination is being replaced by
	43	* the source, so the question is whether the EA should be applied to the
	44	* destination, or generated anew.
	45	*
	46	* CopyOperationIntentShare indicates that the EA is attached to an object that
	47	* is being given out to other people. For example, saving to a public folder,
	48	* or attaching to an email message.
	49	*/
	50
	51	typedef enum {
	52	CopyOperationIntentCopy = 1,
	53	CopyOperationIntentSave,
	54	CopyOperationIntentShare,
	55	} CopyOperationIntent_t;
	56
	57	typedef uint64_t CopyOperationProperties_t;
	58
	59	/*
	60	* Various properties used to determine how to handle the xattr during
	61	* copying. The intent is that the default is reasonable for most xattrs.
	62	*/
	63
	64	/*
	65	* kCopyOperationPropertyNoExport
	66	* Declare that the extended property should not be exported; this is
	67	* deliberately a bit vague, but this is used by CopyOperationIntentShare
	68	* to indicate not to preserve the xattr.
	69	*/
	70	#define kCopyOperationPropertyNoExport ((CopyOperationProperties_t)0x0001)
	71
	72	/*
	73	* kCopyOperationPropertyContentDependent
	74	* Declares the extended attribute to be tied to the contents of the file (or
	75	* vice versa), such that it should be re-created when the contents of the
	76	* file change. Examples might include cryptographic keys, checksums, saved
	77	* position or search information, and text encoding.
	78	*
	79	* This property causes the EA to be preserved for copy and share, but not for
	80	* safe save. (In a safe save, the EA exists on the original, and will not
	81	* be copied to the new version.)
	82	*/
	83	#define kCopyOperationPropertyContentDependent ((CopyOperationProperties_t)0x0002)
	84
	85	/*
	86	* kCopyOperationPropertyNeverPreserve
	87	* Declares that the extended attribute is never to be copied, for any
	88	* intention type.
	89	*/
	90	#define kCopyOperationPropertyNeverPreserve ((CopyOperationProperties_t)0x0004)
	91
618b37c8 A	92	#if 0
	93	/*
	94	* These are all going to be removed, and I don't believe anyone used them.
	95	*/
11f767b3 A	96	/*
	97	* Given an extended attribute name, and a set of properties, return an
	98	* allocated C string with the name. This will return NULL on error;
	99	* errno may be set to ENOMEM if the new name cannot be allocated, or
	100	* ENAMETOOLONG if the new name is longer than the maximum for EAs (127 UTF8
	101	* characters). The caller must deallocate the return value otherwise.
	102	*
	103	* If no properties are set, it returns a copy of the EA name.
	104	*
	105	* If the EA name is in the internal list, and the properties are the same as
	106	* defined there, then it will also return an unmodified copy of the EA name.
	107	*/
618b37c8	108	extern char _xattrNameWithProperties(const char , CopyOperationProperties_t) DEPRECATED_IN_MAC_OS_X_VERSION_10_10_AND_LATER;
11f767b3 A	109
	110	/*
	111	* Given an extended attribute name, which may or may not have properties encoded
	112	* as a suffix, return just the name of the attribute. E.g., com.example.mine#P
	113	* would return "com.example.mine". The return value will be NULL on error;
	114	* errno will be set to ENOMEM if it cannot be allocated. The caller must deallocate
	115	* the return value.
	116	*/
618b37c8	117	extern char _xattrNameWithoutProperties(const char ) DEPRECATED_IN_MAC_OS_X_VERSION_10_10_AND_LATER;
11f767b3 A	118
	119	/*
	120	* Given an EA name, return the properties. If the name is in the internal list,
	121	* those properties will be returned. Unknown property encodings are ignored.
	122	*/
618b37c8 A	123	extern CopyOperationProperties_t _xattrPropertiesFromName(const char *) DEPRECATED_IN_MAC_OS_X_VERSION_10_10_AND_LATER;
618b37c8 A	124	#endif /* 0 */
11f767b3 A	125
	126	__END_DECLS
	127
	128	#endif /* _XATTR_PROPERTIES_H */