Struct CFURL 

pub struct CFURL { /* private fields */ }

Available on crate feature CFURL only.

Apple’s documentation

This is toll-free bridged with NSURL.

Implementations

impl CFURL

pub unsafe fn with_bytes( allocator: Option<&CFAllocator>, url_bytes: *const u8, length: CFIndex, encoding: CFStringEncoding, base_url: Option<&CFURL>, ) -> Option<CFRetained<CFURL>>

Available on crate feature CFString only.

Safety

• allocator might not allow None.
• url_bytes must be a valid pointer.
• base_url might not allow None.

pub fn new_data( allocator: Option<&CFAllocator>, url: Option<&CFURL>, encoding: CFStringEncoding, escape_whitespace: bool, ) -> Option<CFRetained<CFData>>

Available on crate features CFData and CFString only.

pub unsafe fn new_absolute_url_with_bytes( alloc: Option<&CFAllocator>, relative_url_bytes: *const u8, length: CFIndex, encoding: CFStringEncoding, base_url: Option<&CFURL>, use_compatibility_mode: bool, ) -> Option<CFRetained<CFURL>>

Available on crate feature CFString only.

Safety

• alloc might not allow None.
• relative_url_bytes must be a valid pointer.
• base_url might not allow None.

pub fn with_file_system_path( allocator: Option<&CFAllocator>, file_path: Option<&CFString>, path_style: CFURLPathStyle, is_directory: bool, ) -> Option<CFRetained<CFURL>>

pub unsafe fn from_file_system_representation( allocator: Option<&CFAllocator>, buffer: *const u8, buf_len: CFIndex, is_directory: bool, ) -> Option<CFRetained<CFURL>>

Safety

• allocator might not allow None.
• buffer must be a valid pointer.

pub fn with_file_system_path_relative_to_base( allocator: Option<&CFAllocator>, file_path: Option<&CFString>, path_style: CFURLPathStyle, is_directory: bool, base_url: Option<&CFURL>, ) -> Option<CFRetained<CFURL>>

pub unsafe fn from_file_system_representation_relative_to_base( allocator: Option<&CFAllocator>, buffer: *const u8, buf_len: CFIndex, is_directory: bool, base_url: Option<&CFURL>, ) -> Option<CFRetained<CFURL>>

Safety

• allocator might not allow None.
• buffer must be a valid pointer.
• base_url might not allow None.

pub unsafe fn file_system_representation( &self, resolve_against_base: bool, buffer: *mut u8, max_buf_len: CFIndex, ) -> bool

Safety

buffer must be a valid pointer.

pub fn absolute_url(&self) -> Option<CFRetained<CFURL>>

pub fn base_url(&self) -> Option<CFRetained<CFURL>>

pub fn can_be_decomposed(&self) -> bool

pub fn scheme(&self) -> Option<CFRetained<CFString>>

pub fn net_location(&self) -> Option<CFRetained<CFString>>

pub fn path(&self) -> Option<CFRetained<CFString>>

pub unsafe fn strict_path( &self, is_absolute: *mut u8, ) -> Option<CFRetained<CFString>>

Safety

is_absolute must be a valid pointer.

pub fn file_system_path( &self, path_style: CFURLPathStyle, ) -> Option<CFRetained<CFString>>

pub fn has_directory_path(&self) -> bool

pub fn resource_specifier(&self) -> Option<CFRetained<CFString>>

pub fn host_name(&self) -> Option<CFRetained<CFString>>

pub fn port_number(&self) -> i32

pub fn user_name(&self) -> Option<CFRetained<CFString>>

pub fn password(&self) -> Option<CFRetained<CFString>>

pub fn parameter_string( &self, characters_to_leave_escaped: Option<&CFString>, ) -> Option<CFRetained<CFString>>

👎Deprecated: The CFURLCopyParameterString function is deprecated. Post deprecation for applications linked with or after the macOS 10.15, and for all iOS, watchOS, and tvOS applications, CFURLCopyParameterString will always return NULL, and the CFURLCopyPath(), CFURLCopyStrictPath(), and CFURLCopyFileSystemPath() functions will return the complete path including the semicolon separator and params component if the URL string contains them.

pub fn query_string( &self, characters_to_leave_escaped: Option<&CFString>, ) -> Option<CFRetained<CFString>>

pub fn fragment( &self, characters_to_leave_escaped: Option<&CFString>, ) -> Option<CFRetained<CFString>>

pub fn last_path_component(&self) -> Option<CFRetained<CFString>>

pub fn path_extension(&self) -> Option<CFRetained<CFString>>

pub fn new_copy_appending_path_component( allocator: Option<&CFAllocator>, url: Option<&CFURL>, path_component: Option<&CFString>, is_directory: bool, ) -> Option<CFRetained<CFURL>>

pub fn new_copy_deleting_last_path_component( allocator: Option<&CFAllocator>, url: Option<&CFURL>, ) -> Option<CFRetained<CFURL>>

pub fn new_copy_appending_path_extension( allocator: Option<&CFAllocator>, url: Option<&CFURL>, extension: Option<&CFString>, ) -> Option<CFRetained<CFURL>>

pub fn new_copy_deleting_path_extension( allocator: Option<&CFAllocator>, url: Option<&CFURL>, ) -> Option<CFRetained<CFURL>>

pub unsafe fn bytes(&self, buffer: *mut u8, buffer_length: CFIndex) -> CFIndex

Safety

buffer must be a valid pointer.

impl CFURL

pub unsafe fn byte_range_for_component( &self, component: CFURLComponentType, range_including_separators: *mut CFRange, ) -> CFRange

Safety

range_including_separators must be a valid pointer.

pub fn new_string_by_replacing_percent_escapes( allocator: Option<&CFAllocator>, original_string: Option<&CFString>, characters_to_leave_escaped: Option<&CFString>, ) -> Option<CFRetained<CFString>>

pub unsafe fn new_string_by_replacing_percent_escapes_using_encoding( allocator: Option<&CFAllocator>, orig_string: Option<&CFString>, chars_to_leave_escaped: Option<&CFString>, encoding: CFStringEncoding, ) -> Option<CFRetained<CFString>>

👎Deprecated: Use [NSString stringByRemovingPercentEncoding] or CFURLCreateStringByReplacingPercentEscapes() instead, which always uses the recommended UTF-8 encoding.

Available on crate feature CFString only.

Safety

• allocator might not allow None.
• orig_string might not allow None.
• chars_to_leave_escaped might not allow None.

pub unsafe fn new_string_by_adding_percent_escapes( allocator: Option<&CFAllocator>, original_string: Option<&CFString>, characters_to_leave_unescaped: Option<&CFString>, legal_url_characters_to_be_escaped: Option<&CFString>, encoding: CFStringEncoding, ) -> Option<CFRetained<CFString>>

👎Deprecated: Use [NSString stringByAddingPercentEncodingWithAllowedCharacters:] instead, which always uses the recommended UTF-8 encoding, and which encodes for a specific URL component or subcomponent (since each URL component or subcomponent has different rules for what characters are valid).

Available on crate feature CFString only.

Safety

• allocator might not allow None.
• original_string might not allow None.
• characters_to_leave_unescaped might not allow None.
• legal_url_characters_to_be_escaped might not allow None.

pub fn is_file_reference_url(&self) -> bool

pub unsafe fn new_file_reference_url( allocator: Option<&CFAllocator>, url: Option<&CFURL>, error: *mut *mut CFError, ) -> Option<CFRetained<CFURL>>

Available on crate feature CFError only.

Safety

• allocator might not allow None.
• url might not allow None.
• error must be a valid pointer.

pub unsafe fn new_file_path_url( allocator: Option<&CFAllocator>, url: Option<&CFURL>, error: *mut *mut CFError, ) -> Option<CFRetained<CFURL>>

Available on crate feature CFError only.

Safety

• allocator might not allow None.
• url might not allow None.
• error must be a valid pointer.

pub unsafe fn resource_property_for_key( &self, key: Option<&CFString>, property_value_type_ref_ptr: *mut c_void, error: *mut *mut CFError, ) -> bool

Available on crate feature CFError only.

Safety

• key might not allow None.
• property_value_type_ref_ptr must be a valid pointer.
• error must be a valid pointer.

pub unsafe fn resource_properties_for_keys( &self, keys: Option<&CFArray>, error: *mut *mut CFError, ) -> Option<CFRetained<CFDictionary>>

Available on crate features CFArray and CFDictionary and CFError only.

Safety

• keys generic must be of the correct type.
• keys might not allow None.
• error must be a valid pointer.

pub unsafe fn set_resource_property_for_key( &self, key: Option<&CFString>, property_value: Option<&CFType>, error: *mut *mut CFError, ) -> bool

Available on crate feature CFError only.

Safety

• key might not allow None.
• property_value should be of the correct type.
• property_value might not allow None.
• error must be a valid pointer.

pub unsafe fn set_resource_properties_for_keys( &self, keyed_property_values: Option<&CFDictionary>, error: *mut *mut CFError, ) -> bool

Available on crate features CFDictionary and CFError only.

Safety

• keyed_property_values generics must be of the correct type.
• keyed_property_values might not allow None.
• error must be a valid pointer.

impl CFURL

pub fn clear_resource_property_cache_for_key(&self, key: Option<&CFString>)

pub fn clear_resource_property_cache(&self)

pub fn set_temporary_resource_property_for_key( &self, key: Option<&CFString>, property_value: Option<&CFType>, )

pub unsafe fn resource_is_reachable(&self, error: *mut *mut CFError) -> bool

Available on crate feature CFError only.

Safety

error must be a valid pointer.

impl CFURL

pub unsafe fn new_bookmark_data( allocator: Option<&CFAllocator>, url: Option<&CFURL>, options: CFURLBookmarkCreationOptions, resource_properties_to_include: Option<&CFArray>, relative_to_url: Option<&CFURL>, error: *mut *mut CFError, ) -> Option<CFRetained<CFData>>

Available on crate features CFArray and CFData and CFError only.

Safety

• allocator might not allow None.
• url might not allow None.
• resource_properties_to_include generic must be of the correct type.
• resource_properties_to_include might not allow None.
• relative_to_url might not allow None.
• error must be a valid pointer.

pub unsafe fn new_by_resolving_bookmark_data( allocator: Option<&CFAllocator>, bookmark: Option<&CFData>, options: CFURLBookmarkResolutionOptions, relative_to_url: Option<&CFURL>, resource_properties_to_include: Option<&CFArray>, is_stale: *mut u8, error: *mut *mut CFError, ) -> Option<CFRetained<CFURL>>

Available on crate features CFArray and CFData and CFError only.

Safety

• allocator might not allow None.
• bookmark might not allow None.
• relative_to_url might not allow None.
• resource_properties_to_include generic must be of the correct type.
• resource_properties_to_include might not allow None.
• is_stale must be a valid pointer.
• error must be a valid pointer.

pub unsafe fn new_resource_properties_for_keys_from_bookmark_data( allocator: Option<&CFAllocator>, resource_properties_to_return: Option<&CFArray>, bookmark: Option<&CFData>, ) -> Option<CFRetained<CFDictionary>>

Available on crate features CFArray and CFData and CFDictionary only.

Safety

• allocator might not allow None.
• resource_properties_to_return generic must be of the correct type.
• resource_properties_to_return might not allow None.
• bookmark might not allow None.

pub unsafe fn new_resource_property_for_key_from_bookmark_data( allocator: Option<&CFAllocator>, resource_property_key: Option<&CFString>, bookmark: Option<&CFData>, ) -> Option<CFRetained<CFType>>

Available on crate feature CFData only.

Safety

• allocator might not allow None.
• resource_property_key might not allow None.
• bookmark might not allow None.

pub unsafe fn new_bookmark_data_from_file( allocator: Option<&CFAllocator>, file_url: Option<&CFURL>, error_ref: *mut *mut CFError, ) -> Option<CFRetained<CFData>>

Available on crate features CFData and CFError only.

Safety

• allocator might not allow None.
• file_url might not allow None.
• error_ref must be a valid pointer.

pub unsafe fn write_bookmark_data_to_file( bookmark_ref: Option<&CFData>, file_url: Option<&CFURL>, options: CFURLBookmarkFileCreationOptions, error_ref: *mut *mut CFError, ) -> bool

Available on crate features CFData and CFError only.

Safety

• bookmark_ref might not allow None.
• file_url might not allow None.
• error_ref must be a valid pointer.

pub unsafe fn new_bookmark_data_from_alias_record( allocator_ref: Option<&CFAllocator>, alias_record_data_ref: Option<&CFData>, ) -> Option<CFRetained<CFData>>

👎Deprecated: The Carbon Alias Manager is deprecated. This function should only be used to convert Carbon AliasRecords to bookmark data.

Available on crate feature CFData only.

Safety

• allocator_ref might not allow None.
• alias_record_data_ref might not allow None.

pub unsafe fn start_accessing_security_scoped_resource(&self) -> bool

pub unsafe fn stop_accessing_security_scoped_resource(&self)

impl CFURL

pub unsafe fn new_data_and_properties_from_resource( alloc: Option<&CFAllocator>, url: Option<&CFURL>, resource_data: *mut *const CFData, properties: *mut *const CFDictionary, desired_properties: Option<&CFArray>, error_code: *mut i32, ) -> bool

👎Deprecated: For resource data, use the CFReadStream API. For file resource properties, use CFURLCopyResourcePropertiesForKeys.

Available on crate features CFURLAccess and CFArray and CFData and CFDictionary only.

Safety

• alloc might not allow None.
• url might not allow None.
• resource_data must be a valid pointer.
• properties must be a valid pointer.
• desired_properties generic must be of the correct type.
• desired_properties might not allow None.
• error_code must be a valid pointer.

pub unsafe fn write_data_and_properties_to_resource( &self, data_to_write: Option<&CFData>, properties_to_write: Option<&CFDictionary>, error_code: *mut i32, ) -> bool

👎Deprecated: For resource data, use the CFWriteStream API. For file resource properties, use CFURLSetResourcePropertiesForKeys.

Available on crate features CFURLAccess and CFData and CFDictionary only.

Safety

• data_to_write might not allow None.
• properties_to_write generics must be of the correct type.
• properties_to_write might not allow None.
• error_code must be a valid pointer.

pub unsafe fn destroy_resource(&self, error_code: *mut i32) -> bool

👎Deprecated: Use CFURLGetFileSystemRepresentation and removefile(3) instead.

Available on crate feature CFURLAccess only.

Safety

error_code must be a valid pointer.

pub unsafe fn new_property_from_resource( alloc: Option<&CFAllocator>, url: Option<&CFURL>, property: Option<&CFString>, error_code: *mut i32, ) -> Option<CFRetained<CFType>>

👎Deprecated: For file resource properties, use CFURLCopyResourcePropertyForKey.

Available on crate feature CFURLAccess only.

Safety

• alloc might not allow None.
• url might not allow None.
• property might not allow None.
• error_code must be a valid pointer.

impl CFURL

Path conversion.

pub fn from_file_path<P: AsRef<Path>>(path: P) -> Option<CFRetained<CFURL>>

Available on crate feature std and Unix only.

Create a file url from a Path.

This is useful because a lot of CoreFoundation APIs use CFURL to represent file-system paths as well.

Non-unicode parts of the URL will be percent-encoded, and the url will have the scheme file://.

If the path is relative, it will be considered relative to the current directory.

Returns None when given an invalid path (such as a path containing interior NUL bytes). The exact checks are not guaranteed.

Examples

use std::path::Path;
use objc2_core_foundation::CFURL;

// Absolute paths work as you'd expect.
let url = CFURL::from_file_path("/tmp/file.txt").unwrap();
assert_eq!(url.to_file_path().unwrap(), Path::new("/tmp/file.txt"));

// Relative paths are relative to the current directory.
let url = CFURL::from_file_path("foo.txt").unwrap();
assert_eq!(url.to_file_path().unwrap(), std::env::current_dir().unwrap().join("foo.txt"));

// Some invalid paths return `None`.
assert!(CFURL::from_file_path("").is_none());
// Another example of an invalid path containing interior NUL bytes.
assert!(CFURL::from_file_path("/a/\0a").is_none());

// Trailing NUL bytes are stripped.
// NOTE: This only seems to work on some versions of CoreFoundation.
let url = CFURL::from_file_path("/a\0\0").unwrap();
assert_eq!(url.to_file_path().unwrap(), Path::new("/a"));

pub fn from_directory_path<P: AsRef<Path>>(path: P) -> Option<CFRetained<CFURL>>

Available on crate feature std and Unix only.

Create a directory url from a Path.

This differs from from_file_path in that the path is treated as a directory, which means that other normalization rules are applied to it (to make it end with a /).

Examples

use std::path::Path;
use objc2_core_foundation::CFURL;

// Directory paths get trailing slashes appended
let url = CFURL::from_directory_path("/Library").unwrap();
assert_eq!(url.to_file_path().unwrap(), Path::new("/Library/"));

// Unless they already have them.
let url = CFURL::from_directory_path("/Library/").unwrap();
assert_eq!(url.to_file_path().unwrap(), Path::new("/Library/"));

// Similarly for relative paths.
let url = CFURL::from_directory_path("foo").unwrap();
assert_eq!(url.to_file_path().unwrap(), std::env::current_dir().unwrap().join("foo/"));

// Various dots may be stripped.
let url = CFURL::from_directory_path("/Library/././.").unwrap();
assert_eq!(url.to_file_path().unwrap(), Path::new("/Library/"));

// Though of course not if they have semantic meaning.
let url = CFURL::from_directory_path("/Library/..").unwrap();
assert_eq!(url.to_file_path().unwrap(), Path::new("/Library/.."));

pub fn to_file_path(&self) -> Option<PathBuf>

Available on crate feature std and Unix only.

Extract the path part of the URL as a PathBuf.

This will return a path regardless of whether the scheme is file://. It is the responsibility of the caller to ensure that the URL is valid to use as a file URL.

Compatibility note

This currently does not work for non-unicode paths (which are fairly rare on macOS since HFS+ was been superseded by APFS).

This also currently always returns absolute paths (it converts relative URL paths to absolute), but that may change in the future.

Examples

use std::path::Path;
use objc2_core_foundation::{CFURL, CFString};

let url = CFURL::from_string(None, &CFString::from_str("file:///tmp/foo.txt"), None).unwrap();
assert_eq!(url.to_file_path().unwrap(), Path::new("/tmp/foo.txt"));

See also the examples in from_file_path.

impl CFURL

String conversion.

pub fn from_string( allocator: Option<&CFAllocator>, url_string: &CFString, base_url: Option<&CFURL>, ) -> Option<CFRetained<Self>>

Create an URL from a CFString.

Returns None if the URL is considered invalid by CoreFoundation. The exact details of which strings are invalid URLs are considered an implementation detail.

Note in particular that not all strings that the URL spec considers invalid are considered invalid by CoreFoundation too. If you need spec-compliant parsing, consider the url crate instead.

Examples

Construct and inspect a CFURL.

use objc2_core_foundation::{
    CFString, CFURL, CFURLCopyHostName, CFURLCopyScheme, CFURLCopyPath,
};

let url = CFURL::from_string(None, &CFString::from_str("http://example.com/foo"), None).unwrap();
assert_eq!(url.string().to_string(), "http://example.com/foo");
assert_eq!(CFURLCopyScheme(&url).unwrap().to_string(), "http");
assert_eq!(CFURLCopyHostName(&url).unwrap().to_string(), "example.com");
assert_eq!(CFURLCopyPath(&url).unwrap().to_string(), "/foo");

Fail parsing certain strings.

use objc2_core_foundation::{CFString, CFURL};

// Percent-encoding needs two characters.
assert_eq!(CFURL::from_string(None, &CFString::from_str("http://example.com/%A"), None), None);

// Two hash-characters is disallowed.
assert_eq!(CFURL::from_string(None, &CFString::from_str("http://example.com/abc#a#b"), None), None);

pub unsafe fn from_str_unchecked(s: &str) -> Option<CFRetained<Self>>

Available on crate feature CFString only.

Create an URL from a string without checking it for validity.

Returns None on some OS versions when the string contains interior NUL bytes.

Safety

The URL must be valid.

Note that it is unclear whether this is actually a safety requirement, or simply a correctness requirement. So we conservatively mark this function as unsafe.

pub fn string(&self) -> CFRetained<CFString>

Get the string-representation of the URL.

The string may be overly sanitized (percent-encoded), do not rely on this returning exactly the same string as was passed in from_string.

Methods from Deref<Target = CFType>

pub fn downcast_ref<T: ConcreteType>(&self) -> Option<&T>

Attempt to downcast the type to that of type T.

This is the reference-variant. Use CFRetained::downcast if you want to convert a retained type. See also ConcreteType for more details on which types support being converted to.

pub fn retain_count(&self) -> usize

Get the reference count of the object.

This function may be useful for debugging. You normally do not use this function otherwise.

Beware that some things (like CFNumbers, small CFStrings etc.) may not have a normal retain count for optimization purposes, and can return usize::MAX in that case.

Trait Implementations

impl AsRef<AnyObject> for CFURL

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CFType> for CFURL

fn as_ref(&self) -> &CFType

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CFURL> for CFURL

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for CFURL

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CFType> for CFURL

fn borrow(&self) -> &CFType

Immutably borrows from an owned value.

impl ConcreteType for CFURL

fn type_id() -> CFTypeID

Get the unique CFTypeID identifier for the type.

impl Debug for CFURL

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for CFURL

type Target = CFType

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for CFURL

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for CFURL

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl PartialEq for CFURL

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for CFURL

const ENCODING_REF: Encoding

The Objective-C type-encoding for a reference of this type.

impl Type for CFURL

fn retain(&self) -> CFRetained<Self>

where Self: Sized,

Increment the reference count of the receiver.

fn as_concrete_TypeRef(&self) -> &Self

👎Deprecated: this is redundant

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_get_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::retain

Helper for easier transition from the core-foundation crate.

fn as_CFTypeRef(&self) -> &CFType

where Self: AsRef<CFType>,

👎Deprecated: this is redundant (CF types deref to CFType)

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_create_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::from_raw

Helper for easier transition from the core-foundation crate.

impl Eq for CFURL

impl Send for CFURL

impl Sync for CFURL