ham_entity_handle(), ham_entity_handle_node()

Получить дескриптор объекта

Прототип:

#include <ha/ham.h>
                                       
ham_entity_t * ham_entity_handle( int nd,
                                  const char *ename,
                                  unsigned flags );
                                       
ham_entity_t * ham_entity_handle_node( const char *nodename,
                                       const char *ename,
                                       unsigned flags );

Аргументы:

nd

Идентификатор целевого удаленного узла. По умолчанию используется 0 или ND_LOCAL_NODE для локального узла.

nodename

Целевой удаленный HAM. Если указано NULL, то параметр будет проигнорирован.

ename

Имя объекта.

flags

Флаги в настоящий момент не поддерживаются.

Библиотека:

libham

Описание:

Функция ham_entity_handle() возвращает дескриптор объекта ename. Затем дескриптор может быть передан другим функциям, например, ham_condition() или ham_entity_handle_free().

---

Чтобы получить дескриптор глобального объекта, следует передать NULL в ename.

---

Возвращаемый дескриптор непрозрачен — его содержимое доступно только для внутренних нужд библиотеки.

Если узел (nd) явно указан, то дескриптор относится к комбинации объект/условие/действие, которая относится к процессу на данном удаленном узле. Функция ham_entity_handle_node() используется, когда nodename используется для указания удаленного HAM вместо идентификатора узла (nd).

Возвращаемое значение:

Адрес

Корректный ham_entity_t.

NULL

Возникла ошибка. Код ошибки записан в errno.

Коды ошибок:

EINVAL

Имя, указанное в ename, некорректно (например, оно содержит символ /).

ENAMETOOLONG

Указанное имя ename слишком длинное, т.е. оно превышает _POSIX_PATH_MAX (определено в <limits.h>). Следует обратить внимание, что общая длина имени объекта/условия/действия также ограничена _POSIX_PATH_MAX.

ENOENT

В текущем контексте HAM не определен объект с таким именем.

ENOMEM

Недостаточно памяти для создания нового дескриптора.

Классификация:

ЗОСРВ «Нейтрино»

Безопасность использования

Точка остановки потока

Нет

Обработчик прерываний

Нет

Обработчик сигналов

Нет

В потоке

Да

Предостережения:

Вызов ham_entity_handle() и последующее использование дескриптора, возвращенного в таком вызове, как ham_condition(), полностью асинхронны. Следовательно, действие/условие/объект может более не существовать к тому моменту, когда дескриптор будет использоваться позднее.

В таком случае функции ham_condition*() вернут ошибку ENOENT, означающую, что действие для условия в объекте не существует.

Тематические ссылки:

ham_action_handle(), ham_action_handle_free(), ham_condition(), ham_condition_handle(), ham_condition_handle_free(), ham_condition_remove(), ham_entity_handle_free()

Предыдущий раздел: Менеджер высокой готовности (HAM)