+285

crates/platform/src/cf.rs

reviewed

··· 1 1 + //! Minimal CoreFoundation bindings. 2 2 + //! 3 3 + //! Provides `CFStringRef` creation from Rust strings and RAII reference 4 4 + //! counting via [`CfString`]. These bindings are needed for passing string 5 5 + //! parameters to AppKit APIs (window titles, menu items, etc). 6 6 + //! 7 7 + //! # Safety 8 8 + //! 9 9 + //! This module contains `unsafe` code for FFI with CoreFoundation. 10 10 + //! The `platform` crate is one of the few crates where `unsafe` is permitted. 11 11 + 12 12 + use std::fmt; 13 13 + use std::os::raw::c_void; 14 14 + use std::ptr::NonNull; 15 15 + 16 16 + // --------------------------------------------------------------------------- 17 17 + // Raw FFI types 18 18 + // --------------------------------------------------------------------------- 19 19 + 20 20 + /// Opaque CoreFoundation string type. 21 21 + #[repr(C)] 22 22 + pub struct __CFString { 23 23 + _private: [u8; 0], 24 24 + } 25 25 + 26 26 + /// A reference to a CoreFoundation string (immutable). 27 27 + pub type CFStringRef = *const __CFString; 28 28 + 29 29 + /// CoreFoundation index/size type. 30 30 + pub type CFIndex = isize; 31 31 + 32 32 + /// CoreFoundation string encoding identifier. 33 33 + pub type CFStringEncoding = u32; 34 34 + 35 35 + /// CoreFoundation Boolean type. 36 36 + pub type CFBoolean = u8; 37 37 + 38 38 + /// UTF-8 encoding constant. 39 39 + pub const K_CF_STRING_ENCODING_UTF8: CFStringEncoding = 0x0800_0100; 40 40 + 41 41 + // --------------------------------------------------------------------------- 42 42 + // Raw FFI bindings to CoreFoundation.framework 43 43 + // --------------------------------------------------------------------------- 44 44 + 45 45 + #[link(name = "CoreFoundation", kind = "framework")] 46 46 + extern "C" { 47 47 + fn CFStringCreateWithBytes( 48 48 + alloc: *const c_void, 49 49 + bytes: *const u8, 50 50 + num_bytes: CFIndex, 51 51 + encoding: CFStringEncoding, 52 52 + is_external_representation: CFBoolean, 53 53 + ) -> CFStringRef; 54 54 + 55 55 + fn CFRetain(cf: *const c_void) -> *const c_void; 56 56 + fn CFRelease(cf: *const c_void); 57 57 + 58 58 + fn CFStringGetLength(string: CFStringRef) -> CFIndex; 59 59 + fn CFStringGetCString( 60 60 + string: CFStringRef, 61 61 + buffer: *mut u8, 62 62 + buffer_size: CFIndex, 63 63 + encoding: CFStringEncoding, 64 64 + ) -> CFBoolean; 65 65 + } 66 66 + 67 67 + // --------------------------------------------------------------------------- 68 68 + // Public wrappers for CFRetain / CFRelease 69 69 + // --------------------------------------------------------------------------- 70 70 + 71 71 + /// Increment the reference count of a CoreFoundation object. 72 72 + /// 73 73 + /// # Safety 74 74 + /// 75 75 + /// `ptr` must point to a valid CoreFoundation object. 76 76 + #[inline] 77 77 + pub unsafe fn cf_retain(ptr: *const c_void) -> *const c_void { 78 78 + CFRetain(ptr) 79 79 + } 80 80 + 81 81 + /// Decrement the reference count of a CoreFoundation object. 82 82 + /// 83 83 + /// # Safety 84 84 + /// 85 85 + /// `ptr` must point to a valid CoreFoundation object with a positive 86 86 + /// reference count. The object may be deallocated after this call. 87 87 + #[inline] 88 88 + pub unsafe fn cf_release(ptr: *const c_void) { 89 89 + CFRelease(ptr); 90 90 + } 91 91 + 92 92 + // --------------------------------------------------------------------------- 93 93 + // CfString — RAII wrapper around CFStringRef 94 94 + // --------------------------------------------------------------------------- 95 95 + 96 96 + /// An owned CoreFoundation string that calls `CFRelease` on drop. 97 97 + /// 98 98 + /// Created from a Rust `&str` via [`CfString::new`]. The underlying 99 99 + /// `CFStringRef` can be borrowed with [`CfString::as_cf_ref`] for passing 100 100 + /// to AppKit APIs. 101 101 + pub struct CfString(NonNull<__CFString>); 102 102 + 103 103 + impl CfString { 104 104 + /// Create a `CfString` from a Rust string slice. 105 105 + /// 106 106 + /// Returns `None` if CoreFoundation fails to create the string (should 107 107 + /// only happen for extremely large strings or out-of-memory conditions). 108 108 + pub fn new(s: &str) -> Option<CfString> { 109 109 + let ptr = unsafe { 110 110 + CFStringCreateWithBytes( 111 111 + std::ptr::null(), // default allocator 112 112 + s.as_ptr(), 113 113 + s.len() as CFIndex, 114 114 + K_CF_STRING_ENCODING_UTF8, 115 115 + 0, // not external representation 116 116 + ) 117 117 + }; 118 118 + // CFStringCreateWithBytes returns null on failure. 119 119 + NonNull::new(ptr as *mut __CFString).map(CfString) 120 120 + } 121 121 + 122 122 + /// Return the raw `CFStringRef` for passing to CoreFoundation / AppKit APIs. 123 123 + #[inline] 124 124 + pub fn as_cf_ref(&self) -> CFStringRef { 125 125 + self.0.as_ptr() as CFStringRef 126 126 + } 127 127 + 128 128 + /// Return the raw pointer as `*const c_void` for APIs that take a generic 129 129 + /// CoreFoundation type reference. 130 130 + #[inline] 131 131 + pub fn as_void_ptr(&self) -> *const c_void { 132 132 + self.0.as_ptr() as *const c_void 133 133 + } 134 134 + 135 135 + /// Get the length of the string in UTF-16 code units. 136 136 + pub fn len(&self) -> usize { 137 137 + let len = unsafe { CFStringGetLength(self.as_cf_ref()) }; 138 138 + len as usize 139 139 + } 140 140 + 141 141 + /// Returns `true` if the string is empty. 142 142 + pub fn is_empty(&self) -> bool { 143 143 + self.len() == 0 144 144 + } 145 145 + 146 146 + /// Try to extract the string contents as a Rust `String`. 147 147 + /// 148 148 + /// This is primarily useful for testing and debugging. 149 149 + pub fn to_string_lossy(&self) -> String { 150 150 + // Allocate a buffer large enough for the UTF-8 representation. 151 151 + // CFStringGetCString needs space for a NUL terminator. 152 152 + // Worst case: each UTF-16 code unit -> 3 UTF-8 bytes + NUL. 153 153 + let max_len = self.len() * 3 + 1; 154 154 + let mut buf = vec![0u8; max_len]; 155 155 + 156 156 + let ok = unsafe { 157 157 + CFStringGetCString( 158 158 + self.as_cf_ref(), 159 159 + buf.as_mut_ptr(), 160 160 + buf.len() as CFIndex, 161 161 + K_CF_STRING_ENCODING_UTF8, 162 162 + ) 163 163 + }; 164 164 + 165 165 + if ok != 0 { 166 166 + // Find the NUL terminator. 167 167 + let nul_pos = buf.iter().position(|&b| b == 0).unwrap_or(buf.len()); 168 168 + String::from_utf8_lossy(&buf[..nul_pos]).into_owned() 169 169 + } else { 170 170 + String::new() 171 171 + } 172 172 + } 173 173 + } 174 174 + 175 175 + impl Clone for CfString { 176 176 + fn clone(&self) -> CfString { 177 177 + unsafe { cf_retain(self.as_void_ptr()) }; 178 178 + CfString(self.0) 179 179 + } 180 180 + } 181 181 + 182 182 + impl Drop for CfString { 183 183 + fn drop(&mut self) { 184 184 + unsafe { cf_release(self.as_void_ptr()) }; 185 185 + } 186 186 + } 187 187 + 188 188 + impl fmt::Debug for CfString { 189 189 + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 190 190 + write!(f, "CfString(\"{}\")", self.to_string_lossy()) 191 191 + } 192 192 + } 193 193 + 194 194 + impl fmt::Display for CfString { 195 195 + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 196 196 + write!(f, "{}", self.to_string_lossy()) 197 197 + } 198 198 + } 199 199 + 200 200 + // SAFETY: CFString is an immutable, reference-counted CoreFoundation type. 201 201 + // CFRetain/CFRelease are thread-safe. 202 202 + unsafe impl Send for CfString {} 203 203 + unsafe impl Sync for CfString {} 204 204 + 205 205 + // --------------------------------------------------------------------------- 206 206 + // Tests 207 207 + // --------------------------------------------------------------------------- 208 208 + 209 209 + #[cfg(test)] 210 210 + mod tests { 211 211 + use super::*; 212 212 + 213 213 + #[test] 214 214 + fn create_cfstring_from_str() { 215 215 + let s = CfString::new("Hello, world!").expect("should create CFString"); 216 216 + assert_eq!(s.to_string_lossy(), "Hello, world!"); 217 217 + } 218 218 + 219 219 + #[test] 220 220 + fn cfstring_length() { 221 221 + let s = CfString::new("abc").expect("should create CFString"); 222 222 + assert_eq!(s.len(), 3); 223 223 + } 224 224 + 225 225 + #[test] 226 226 + fn cfstring_empty() { 227 227 + let s = CfString::new("").expect("should create empty CFString"); 228 228 + assert!(s.is_empty()); 229 229 + assert_eq!(s.len(), 0); 230 230 + assert_eq!(s.to_string_lossy(), ""); 231 231 + } 232 232 + 233 233 + #[test] 234 234 + fn cfstring_unicode() { 235 235 + let s = CfString::new("caf\u{00e9}").expect("should handle unicode"); 236 236 + assert_eq!(s.to_string_lossy(), "caf\u{00e9}"); 237 237 + // "caf\u{e9}" is 4 UTF-16 code units 238 238 + assert_eq!(s.len(), 4); 239 239 + } 240 240 + 241 241 + #[test] 242 242 + fn cfstring_emoji() { 243 243 + // Emoji outside BMP: encoded as surrogate pair in UTF-16 (2 code units) 244 244 + let s = CfString::new("\u{1F600}").expect("should handle emoji"); 245 245 + assert_eq!(s.to_string_lossy(), "\u{1F600}"); 246 246 + assert_eq!(s.len(), 2); // surrogate pair 247 247 + } 248 248 + 249 249 + #[test] 250 250 + fn cfstring_clone_and_drop() { 251 251 + let s = CfString::new("test clone").expect("should create"); 252 252 + let s2 = s.clone(); 253 253 + assert_eq!(s.to_string_lossy(), s2.to_string_lossy()); 254 254 + // Both should be droppable without crash (refcount was incremented). 255 255 + drop(s); 256 256 + assert_eq!(s2.to_string_lossy(), "test clone"); 257 257 + } 258 258 + 259 259 + #[test] 260 260 + fn cfstring_debug_format() { 261 261 + let s = CfString::new("debug").expect("should create"); 262 262 + let debug = format!("{:?}", s); 263 263 + assert!(debug.contains("CfString")); 264 264 + assert!(debug.contains("debug")); 265 265 + } 266 266 + 267 267 + #[test] 268 268 + fn cfstring_display_format() { 269 269 + let s = CfString::new("display").expect("should create"); 270 270 + let display = format!("{}", s); 271 271 + assert_eq!(display, "display"); 272 272 + } 273 273 + 274 274 + #[test] 275 275 + fn cfstring_as_cf_ref_not_null() { 276 276 + let s = CfString::new("ptr test").expect("should create"); 277 277 + assert!(!s.as_cf_ref().is_null()); 278 278 + } 279 279 + 280 280 + #[test] 281 281 + fn cfstring_as_void_ptr_not_null() { 282 282 + let s = CfString::new("void test").expect("should create"); 283 283 + assert!(!s.as_void_ptr().is_null()); 284 284 + } 285 285 + }

+1

crates/platform/src/lib.rs

reviewed

··· 1 1 //! Minimal macOS platform layer — Obj-C FFI, AppKit, CoreGraphics, Metal. 2 2 3 3 + pub mod cf; 3 4 pub mod objc;