/* Copyright 2018-2019 Mozilla Foundation
*
* Licensed under the Apache License (Version 2.0), or the MIT license,
* (the "Licenses") at your option. You may not use this file except in
* compliance with one of the Licenses. You may obtain copies of the
* Licenses at:
*
*
http://www.apache.org/licenses/LICENSE-2.0
*
http://opensource.org/licenses/MIT
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the Licenses is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the Licenses for the specific language governing permissions and
* limitations under the Licenses. */
use std::ffi::CStr;
use std::marker::PhantomData;
use std::os::raw::c_char;
/// `FfiStr<'a>` is a safe (`#[repr(transparent)]`) wrapper around a
/// nul-terminated `*const c_char` (e.g. a C string). Conceptually, it is
/// similar to [`std::ffi::CStr`], except that it may be used in the signatures
/// of extern "C" functions.
///
/// Functions accepting strings should use this instead of accepting a C string
/// directly. This allows us to write those functions using safe code without
/// allowing safe Rust to cause memory unsafety.
///
/// A single function for constructing these from Rust ([`FfiStr::from_raw`])
/// has been provided. Most of the time, this should not be necessary, and users
/// should accept `FfiStr` in the parameter list directly.
///
/// ## Caveats
///
/// An effort has been made to make this struct hard to misuse, however it is
/// still possible, if the `'static` lifetime is manually specified in the
/// struct. E.g.
///
/// ```rust,no_run
/// # use ffi_support::FfiStr;
/// // NEVER DO THIS
/// #[no_mangle]
/// extern "C" fn never_do_this(s: FfiStr<'static>) {
/// // save `s` somewhere, and access it after this
/// // function returns.
/// }
/// ```
///
/// Instead, one of the following patterns should be used:
///
/// ```
/// # use ffi_support::FfiStr;
/// #[no_mangle]
/// extern "C" fn valid_use_1(s: FfiStr<'_>) {
/// // Use of `s` after this function returns is impossible
/// }
/// // Alternative:
/// #[no_mangle]
/// extern "C" fn valid_use_2(s: FfiStr) {
/// // Use of `s` after this function returns is impossible
/// }
/// ```
#[repr(transparent)]
pub struct FfiStr<'a> {
cstr: *const c_char,
_boo: PhantomData<&'a ()>,
}
impl<'a> FfiStr<'a> {
/// Construct an `FfiStr` from a raw pointer.
///
/// This should not be needed most of the time, and users should instead
/// accept `FfiStr` in function parameter lists.
///
/// # Safety
///
/// Dereferences a pointer and is thus unsafe.
#[inline]
pub unsafe fn from_raw(ptr: *const c_char) -> Self {
Self {
cstr: ptr,
_boo: PhantomData,
}
}
/// Construct a FfiStr from a `std::ffi::CStr`. This is provided for
/// completeness, as a safe method of producing an `FfiStr` in Rust.
#[inline]
pub fn from_cstr(cstr: &'a CStr) -> Self {
Self {
cstr: cstr.as_ptr(),
_boo: PhantomData,
}
}
/// Get an `&str` out of the `FfiStr`. This will panic in any case that
/// [`FfiStr::as_opt_str`] would return `None` (e.g. null pointer or invalid
/// UTF-8).
///
/// If the string should be optional, you should use [`FfiStr::as_opt_str`]
/// instead. If an owned string is desired, use [`FfiStr::into_string`] or
/// [`FfiStr::into_opt_string`].
#[inline]
pub fn as_str(&self) -> &'a str {
self.as_opt_str()
.expect("Unexpected null string pointer passed to rust")
}
/// Get an `Option<&str>` out of the `FfiStr`. If this stores a null
/// pointer, then None will be returned. If a string containing invalid
/// UTF-8 was passed, then an error will be logged and `None` will be
/// returned.
///
/// If the string is a required argument, use [`FfiStr::as_str`], or
/// [`FfiStr::into_string`] instead. If `Option<String>` is desired, use
/// [`FfiStr::into_opt_string`] (which will handle invalid UTF-8 by
/// replacing with the replacement character).
pub fn as_opt_str(&self) -> Option<&'a str> {
if self.cstr.is_null() {
return None;
}
unsafe {
match std::ffi::CStr::from_ptr(self.cstr).to_str() {
Ok(s) => Some(s),
Err(e) => {
log::error!("Invalid UTF-8 was passed to rust! {:?}", e);
None
}
}
}
}
/// Get an `Option<String>` out of the `FfiStr`. Returns `None` if this
/// `FfiStr` holds a null pointer. Note that unlike [`FfiStr::as_opt_str`],
/// invalid UTF-8 is replaced with the replacement character instead of
/// causing us to return None.
///
/// If the string should be mandatory, you should use
/// [`FfiStr::into_string`] instead. If an owned string is not needed, you
/// may want to use [`FfiStr::as_str`] or [`FfiStr::as_opt_str`] instead,
/// (however, note the differences in how invalid UTF-8 is handled, should
/// this be relevant to your use).
pub fn into_opt_string(self) -> Option<String> {
if !self.cstr.is_null() {
unsafe { Some(CStr::from_ptr(self.cstr).to_string_lossy().to_string()) }
} else {
None
}
}
/// Get a `String` out of a `FfiStr`. This function is essential a
/// convenience wrapper for `ffi_str.into_opt_string().unwrap()`, with a
/// message that indicates that a null argument was passed to rust when it
/// should be mandatory. As with [`FfiStr::into_opt_string`], invalid UTF-8
/// is replaced with the replacement character if encountered.
///
/// If the string should *not* be mandatory, you should use
/// [`FfiStr::into_opt_string`] instead. If an owned string is not needed,
/// you may want to use [`FfiStr::as_str`] or [`FfiStr::as_opt_str`]
/// instead, (however, note the differences in how invalid UTF-8 is handled,
/// should this be relevant to your use).
#[inline]
pub fn into_string(self) -> String {
self.into_opt_string()
.expect("Unexpected null string pointer passed to rust")
}
}
impl<'a> std::fmt::Debug for FfiStr<'a> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
if let Some(s) = self.as_opt_str() {
write!(f, "FfiStr({:?})", s)
} else {
write!(f, "FfiStr(null)")
}
}
}
// Conversions...
impl<'a> From<FfiStr<'a>> for String {
#[inline]
fn from(f: FfiStr<'a>) -> Self {
f.into_string()
}
}
impl<'a> From<FfiStr<'a>> for Option<String> {
#[inline]
fn from(f: FfiStr<'a>) -> Self {
f.into_opt_string()
}
}
impl<'a> From<FfiStr<'a>> for Option<&'a str> {
#[inline]
fn from(f: FfiStr<'a>) -> Self {
f.as_opt_str()
}
}
impl<'a> From<FfiStr<'a>> for &'a str {
#[inline]
fn from(f: FfiStr<'a>) -> Self {
f.as_str()
}
}
// TODO: `AsRef<str>`?
// Comparisons...
// Compare FfiStr with eachother
impl<'a> PartialEq for FfiStr<'a> {
#[inline]
fn eq(&self, other: &FfiStr<'a>) -> bool {
self.as_opt_str() == other.as_opt_str()
}
}
// Compare FfiStr with str
impl<'a> PartialEq<str> for FfiStr<'a> {
#[inline]
fn eq(&self, other: &str) -> bool {
self.as_opt_str() == Some(other)
}
}
// Compare FfiStr with &str
impl<'a, 'b> PartialEq<&'b str> for FfiStr<'a> {
#[inline]
fn eq(&self, other: &&'b str) -> bool {
self.as_opt_str() == Some(*other)
}
}
// rhs/lhs swap version of above
impl<'a> PartialEq<FfiStr<'a>> for str {
#[inline]
fn eq(&self, other: &FfiStr<'a>) -> bool {
Some(self) == other.as_opt_str()
}
}
// rhs/lhs swap...
impl<'a, 'b> PartialEq<FfiStr<'a>> for &'b str {
#[inline]
fn eq(&self, other: &FfiStr<'a>) -> bool {
Some(*self) == other.as_opt_str()
}
}
