Struct Message

pub struct Message(/* private fields */);

Available on macOS only.

A message from Endpoint Security.

Be careful with AUTH messages, they must be responded to before their deadline (see Message::deadline()) else Endpoint Security may kill your client as it slows the OS too much.

Implementation details (macOS 11+)

Behind the scene, es_message_t is a reference-counted object, which means Clone-ing a Message won’t actually create a new message, but merely increment its refcount and return a new handle to that object. This is very cheap and can be done without much performance overhead.

Implementation details (macOS 10.15.x)

Dropping a Message while inside a handler may cause your app to crash. We copy the message before handing it over for your usage but that may not be enough, so be thorough in testing.

See https://developer.apple.com/documentation/endpointsecurity/3366178-es_free_message.

Implementations

impl Message

pub unsafe fn from_raw(msg: NonNull<es_message_t>) -> Self

Create a new Message from a raw pointer.

Safety

msg must point to a valid live es_message_t object.

Details

On macOS 11.0+, with the feature "macos_11_0_0" (or more) active, this uses es_retain_message(), which is basically an Arc::clone().

On macOS 10.15.x, this calls es_copy_message().

pub fn version(&self) -> u32

Version of the Endpoint Security message.

pub fn raw_time(&self) -> timespec

Time at which the event was generated.

See also Self::time().

Ref: https://developer.apple.com/documentation/kernel/timespec

pub fn time(&self) -> SystemTime

Time at which the event was generated, as a SystemTime.

See also Self::raw_time().

pub fn raw_mach_time(&self) -> u64

Time at which the event was generated, as Mach absolute time.

This is basically a duration since the machine booted up.

See also Self::mach_time().

Ref: https://developer.apple.com/documentation/kernel/1462446-mach_absolute_time

pub fn mach_time(&self) -> Result<Instant, TimeError>

Time at which the event was generated, as an Instant.

This is basically a duration since the machine booted up.

See also Self::raw_mach_time().

pub fn raw_deadline(&self) -> u64

Time before which an AUTH event must be responded to, as Mach absolute time.

Warning: The client needs to respond to auth events prior to the deadline otherwise the application will be killed.

See also Self::deadline().

Ref: https://developer.apple.com/documentation/kernel/1462446-mach_absolute_time

pub fn deadline(&self) -> Result<Instant, TimeError>

Time before which an AUTH event must be responded to, as an Instant.

Warning: The client needs to respond to auth events prior to the deadline otherwise the application will be killed.

See also Self::raw_deadline().

pub fn process(&self) -> Process<'_>

Describes the process that took the action.

pub fn seq_num(&self) -> Option<u64>

Available on crate feature macos_10_15_4 only.

Per client event sequence number on version 2 and later, otherwise None.

pub fn action_type(&self) -> es_action_type_t

Indicates if the action field is an auth or notify action.

pub fn action(&self) -> Option<Action>

For auth events, contains the opaque auth ID that must be supplied when responding to the event. For notify events, describes the result of the action.

pub fn event_type(&self) -> es_event_type_t

Indicates which event struct is defined in the event union.

pub fn event(&self) -> Option<Event<'_>>

Event associated to this message.

pub fn thread(&self) -> Option<Thread<'_>>

Available on crate feature macos_11_0_0 only.

Thread associated to this message (if present) on version 4 and later, otherwise None.

pub fn global_seq_num(&self) -> Option<u64>

Available on crate feature macos_11_0_0 only.

Per client global sequence number on version 4 and later, otherwise None.

Trait Implementations

impl Clone for Message

fn clone(&self) -> Self

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Message

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

Formats the value using the given formatter.

impl Drop for Message

fn drop(&mut self)

Executes the destructor for this type.

impl Hash for Message

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 PartialEq for Message

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

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

const 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 Eq for Message

impl Send for Message

Safety: Message is safe to send across threads - it does not contain any interior mutability, nor depend on current thread state.

impl Sync for Message

Safety: Message is safe to share between threads - it does not contain any interior mutability.