/* omr-watcher.h
 *
 * Copyright (c) 2023-2024 Apple Inc. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * This code adds border router support to 3rd party HomeKit Routers as part of Apple’s commitment to the CHIP project.
 *
 * This file contains the interface for the omr_watcher_t object, which tracks off-mesh-routable prefixes on the
 * Thread network.
 */

#ifndef __OMR_WATCHER_H__
#define __OMR_WATCHER_H__ 1

typedef struct omr_watcher omr_watcher_t;
typedef struct omr_watcher_callback omr_watcher_callback_t;
typedef enum {
    omr_watcher_event_prefix_withdrawn,
    omr_watcher_event_prefix_flags_changed,
    omr_watcher_event_prefix_added,
    omr_watcher_event_prefix_update_finished
} omr_watcher_event_type_t;

typedef enum {
    omr_prefix_priority_invalid,
    omr_prefix_priority_low,
    omr_prefix_priority_medium,
    omr_prefix_priority_high,
} omr_prefix_priority_t;

struct omr_prefix {
    int ref_count;
    omr_prefix_t *NULLABLE next;
    struct in6_addr prefix;
    int prefix_length;
    int metric;
    int rloc;
    int flags;
    omr_prefix_priority_t priority;
    bool user, ncp, stable, onmesh, slaac, dhcp, preferred;
    bool previous_user, previous_ncp, previous_stable;
    bool added, removed, ignore;
    thread_service_publication_state_t publication_state;
};

typedef void (*omr_watcher_event_callback_t)(route_state_t *NONNULL route_state, void *NULLABLE context, omr_watcher_event_type_t event_type,
                                             omr_prefix_t *NULLABLE prefixes, omr_prefix_t *NULLABLE prefix);
typedef void (*omr_watcher_context_release_callback_t)(route_state_t *NONNULL route_state, void *NULLABLE context);

// Release/retain functions for omr_watcher_t:
RELEASE_RETAIN_DECLS(omr_watcher);
#define omr_watcher_retain(watcher) omr_watcher_retain_(watcher, __FILE__, __LINE__)
#define omr_watcher_release(watcher) omr_watcher_release_(watcher, __FILE__, __LINE__)
RELEASE_RETAIN_DECLS(omr_prefix);
#define omr_prefix_retain(prefix) omr_prefix_retain_(prefix, __FILE__, __LINE__)
#define omr_prefix_release(prefix) omr_prefix_release_(prefix, __FILE__, __LINE__)

// omr_prefix_create
//
// Allocate an omr_prefix_t and initialize it with the specified settings.

omr_prefix_t *NULLABLE omr_prefix_create(struct in6_addr *NONNULL prefix, int prefix_length, int metric, int flags,
                                         int rloc, bool stable, bool ncp);

// omr_prefix_flags_generate
//
// Given various common parameters, generate a flags word in the format expected by OpenThread for prefixes.

int omr_prefix_flags_generate(bool on_mesh, bool preferred, bool slaac, omr_prefix_priority_t priority);

// omr_prefix_priority_to_bits
//
// Given an omr_priority_t, return the bits that represent it in the prefix flag word.
//
int omr_prefix_priority_to_bits(omr_prefix_priority_t priority);

// omr_prefix_priority_to_int
//
// Given an omr_priority_t, return the human-readable integer that represents it. Invalid priority is
// returned as -1 (low).
//
int omr_prefix_priority_to_int(omr_prefix_priority_t priority);

// omr_watcher_callback_add
//
// Adds a callback on the omr_watcher object.
//
// watcher: the omr_watcher_t to which to add the callback

#define omr_watcher_callback_add(omw, callback, context_release, context) \
	omr_watcher_callback_add_(omw, callback, context_release, context, __FILE__, __LINE__)
omr_watcher_callback_t *NULLABLE
omr_watcher_callback_add_(omr_watcher_t *NONNULL omw, omr_watcher_event_callback_t NONNULL callback,
                          omr_watcher_context_release_callback_t NULLABLE context_release,
                          void *NULLABLE context, const char *NONNULL file, int line);

// omr_watcher_callback_cancel
//
// Cancel a callback that was returned by omr_watcher_add_callback().
//
// watcher:  the watcher that returned the callback object.
// callback: the callback to free
//
// The object passed in callback should not be retained by the caller after calling omr_watcher_callback_cancel().

void omr_watcher_callback_cancel(omr_watcher_t *NONNULL omw, omr_watcher_callback_t *NONNULL callback);

// omr_watcher_create
//
// Creates and starts an omr_watcher_t object. The object starts an ongoing query with wpantund/threadradiod to watch the Thread:OnMeshPrefixes
// property. Changes are reported to callbacks, which can be registered with
//
// route_state: pointer to a route state object to reference in callbacks, must be non-NULL.
//
// returns value: NULL on failure, or a pointer to an omr_watcher_t object.

#define omr_watcher_create(route_state, disconnect_callback) \
    omr_watcher_create_(route_state, disconnect_callback, __FILE__, __LINE__)
omr_watcher_t *NULLABLE
omr_watcher_create_(route_state_t *NONNULL route_state, void (*NULLABLE disconnect_callback)(void *NONNULL),
                    const char *NONNULL file, int line);

// omr_watcher_start
//
// Starts the omr watcher object. Prior to calling omr_start, no events will be delivered; after calling omr_start, events may be delivered.
//
// watcher: pointer to an omr_watcher_t object to start.
bool omr_watcher_start(omr_watcher_t *NONNULL watcher);


// omr_watcher_cancel
//
// Cancels the omr watcher object. No callbacks can occur after omr_watcher_cancel has been called.
//
// watcher: pointer to an omr_watcher_t object to cancel.
void omr_watcher_cancel(omr_watcher_t *NONNULL watcher);

// omr_watcher_prefix_present
//
// Returns true if there is a prefix in the watcher's prefix list that has the specified priority.
//
// watcher: watcher we use for the search
// ignore_prefix: the prefix we are currently publishing, and hence should ignore
// ignore_prefix_len: length of the prefix we should ignore

bool omr_watcher_prefix_present(omr_watcher_t *NONNULL watcher, omr_prefix_priority_t priority,
                                struct in6_addr *NONNULL ignore_prefix, int ignore_prefix_len);

// omr_watcher_prefix_exists
//
// Returns true if the specified prefix is in the watcher's current prefix list.
//
// watcher: watcher we use for the search
// address: address on prefix to search for
// prefix_len: length of prefix (host bits in address are ignored)

bool omr_watcher_prefix_exists(omr_watcher_t *NONNULL watcher,
                               const struct in6_addr *NONNULL address, int prefix_len);

// omr_watcher_prefix_present
//
// Returns true if there is a prefix in the provided list that has the specified priority.
//
// prefixes: pointer to an omr_prefix_t object to check
// preference: low, medium or high

bool
omr_watcher_prefix_wins(omr_watcher_t *NONNULL watcher, omr_prefix_priority_t priority,
                        struct in6_addr *NONNULL ignore_prefix, int ignore_prefix_length);

// omr_watcher_prefixes_get
//
// Returns the list of prefixes the omr_watcher has most recently seen, or NULL if none.
//

omr_prefix_t *NULLABLE
omr_watcher_prefixes_get(omr_watcher_t *NONNULL watcher);

// omr_watcher_add_prefix
//
// Adds the specified prefix at the specified priority. Returns true if prefix was added, false otherwise.
//

bool
omr_watcher_prefix_add(omr_watcher_t *NONNULL watcher, const void *NONNULL data, int prefix_length, omr_prefix_priority_t priority);

// omr_watcher_prefixes
//
// Deletes the specified prefix. Returns true of it was deleted, false otherwise.
//

bool
omr_watcher_prefix_remove(omr_watcher_t *NONNULL watcher, const void *NONNULL data, int prefix_length);

// omw_watcher_non_ula_prefix_present
//
// Returns true if there is an on-mesh prefix in the thread network data that is not a ULA prefix (implicitly a global prefix)
//

bool omr_watcher_non_ula_prefix_present(omr_watcher_t *NONNULL watcher);


#define omr_watcher_prefix_is_non_ula_prefix(omr_prefix) ((((uint8_t *)&(omr_prefix)->prefix)[0] & 0xfc) != 0xfc)

#endif // _OMR_WATCHER_H__

// Local Variables:
// mode: C
// tab-width: 4
// c-file-style: "bsd"
// c-basic-offset: 4
// fill-column: 120
// indent-tabs-mode: nil
// End: