Client

An opaque type that maintains Endpoint Security client state, and functions related to this type.

Overview

Create an Endpoint Security client with es_new_client, then use this client to subscribe to event types of interest to your app or system extension. When Endpoint Security monitors an event your client subscribes to, it sends a message describing the event to your client. When you no longer need the client, destroy it with es_delete_client.

The following code creates a client and handles any errors returned by es_new_client. If client creation succeeds, the code subscribes the client to the ES_EVENT_TYPE_AUTH_EXEC event. The handler passed to es_new_client allows any such event to proceed.

// Create the client.
es_client_t *client = NULL;
es_new_client_result_t newClientResult =
es_new_client(&client,
              ^(es_client_t * client, const es_message_t * message) {
    switch (message->event_type) {
        case ES_EVENT_TYPE_AUTH_EXEC:
            es_respond_auth_result(client, message, ES_AUTH_RESULT_ALLOW, true);
            break;
        default:
            panic("Found unexpected event type: %i", message->event_type);
            break;
    }
});

// Handle any errors encountered while creating the client.
switch (newClientResult) {
    case ES_NEW_CLIENT_RESULT_SUCCESS:
        // Client created successfully; continue.
        break;
    case ES_NEW_CLIENT_RESULT_ERR_NOT_ENTITLED:
        panic("Extension is missing entitlement.");
        break;
    case ES_NEW_CLIENT_RESULT_ERR_NOT_PRIVILEGED:
        panic ("Extension is not running as root.");
        break;
    case ES_NEW_CLIENT_RESULT_ERR_NOT_PERMITTED:
        // Prompt user to perform TCC approval.
        // This error is recoverable; the user can try again after
        // approving TCC.
        return YOUR_NEW_CLIENT_ERROR_CODE_PROMPT_TCC;
        break;
    case ES_NEW_CLIENT_RESULT_ERR_INVALID_ARGUMENT:
        panic ("Invalid argument to es_new_client(); client or handler was null.");
        break;
    case ES_NEW_CLIENT_RESULT_ERR_TOO_MANY_CLIENTS:
        panic ("Exceeded maximum number of simultaneously-connected ES clients.");
        break;
    case ES_NEW_CLIENT_RESULT_ERR_INTERNAL:
        panic ("Failed to connect to the Endpoint Security subsystem.");
        break;
}

// Subscribe the client to the ES_EVENT_TYPE_AUTH_EXEC event.
// When the client receives a message with this event type, it must authorize
// (allow or deny) the event.
es_event_type_t eventTypes[1] = { ES_EVENT_TYPE_AUTH_EXEC };
es_return_t subscribeResult = es_subscribe(client, eventTypes, sizeof(eventTypes));
if (subscribeResult != ES_RETURN_SUCCESS) {
    panic ("Client failed to subscribe to event."); 
}

Topics

Creating a Client

es_client_t

An opaque type that stores the Endpoint Security client state.

es_new_client

Creates a new client instance and connect it to the Endpoint Security system.

es_handler_block_t

A block that handles a message received from Endpoint Security.

es_new_client_result_t

The result of an attempt to create a new client.

Destroying a Client

es_delete_client

Destroys and disconnects a client instance from the Endpoint Security system.

Subscribing to Events

es_subscribe

Subscribes a client to some set of events.

es_subscriptions

Returns a list of the client’s subscriptions.

es_unsubscribe

Unsubscribes a client from some set of events.

es_event_type_t

A type used to identify a message’s event type and subscribe to events of that type.

es_unsubscribe_all

Unsubscribes a client from all events.

Responding to Events

es_respond_auth_result

Responds to an event that requires an authorization response.

es_auth_result_t

Values used when responding to an authorization event.

es_respond_flags_result

Responds to an event that requires authorization flags as a response.

es_respond_result_t

Values that indicate the result of responding to a message.

Managing Cached Results

es_clear_cache

Clears all cached results for all clients.

es_clear_cache_result_t

Values that indicate the result of clearing a cache.

Muting Events

es_mute_process

Suppresses events from a given process.

es_unmute_process

Restores event delivery from a previously-muted process.

es_muted_processes

Generates a list of muted processes.

es_mute_path_literal

Suppresses events from executables matching a path literal.

es_mute_path_prefix

Suppresses events from executables matching a path prefix.

es_unmute_all_paths

Restores event delivery from previously-muted paths.

Supporting Types

es_return_t

Values that indicate the result of an Endpoint Security action that can only succeed or fail.

See Also

Event Monitoring

Message

A type used by Endpoint Security to notify your client when a monitored action occurs.

Event Types

Types used by messages to deliver details specific to different kinds of Endpoint Security events.