custom_api_device.h

Go to the documentation of this file.

#pragma once
 
#include <map>
#include "api_server.h"
#ifdef USE_API
#ifdef USE_API_USER_DEFINED_ACTIONS
#include "user_services.h"
#endif
namespace esphome::api {
 
#ifdef USE_API_USER_DEFINED_ACTIONS
template<typename T, typename... Ts> class CustomAPIDeviceService : public UserServiceDynamic<Ts...> {
 public:
  CustomAPIDeviceService(const std::string &name, const std::array<std::string, sizeof...(Ts)> &arg_names, T *obj,
                         void (T::*callback)(Ts...))
      : UserServiceDynamic<Ts...>(name, arg_names), obj_(obj), callback_(callback) {}
 
 protected:
  // CustomAPIDevice services don't support action responses - ignore call_id and return_response
  void execute(uint32_t /*call_id*/, bool /*return_response*/, Ts... x) override {
    (this->obj_->*this->callback_)(x...);  // NOLINT
  }
 
  T *obj_;
  void (T::*callback_)(Ts...);
};
#endif  // USE_API_USER_DEFINED_ACTIONS
 
class CustomAPIDevice {
 public:
  bool is_connected() const { return global_api_server->is_connected(); }
 
#ifdef USE_API_USER_DEFINED_ACTIONS
  template<typename T, typename... Ts>
  void register_service(void (T::*callback)(Ts...), const std::string &name,
                        const std::array<std::string, sizeof...(Ts)> &arg_names) {
#ifdef USE_API_CUSTOM_SERVICES
    auto *service = new CustomAPIDeviceService<T, Ts...>(name, arg_names, (T *) this, callback);  // NOLINT
    global_api_server->register_user_service(service);
#else
    static_assert(
        sizeof(T) == 0,
        "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
#endif
  }
#else
  template<typename T, typename... Ts>
  void register_service(void (T::*callback)(Ts...), const std::string &name,
                        const std::array<std::string, sizeof...(Ts)> &arg_names) {
    static_assert(
        sizeof(T) == 0,
        "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
  }
#endif
 
#ifdef USE_API_USER_DEFINED_ACTIONS
  template<typename T> void register_service(void (T::*callback)(), const std::string &name) {
#ifdef USE_API_CUSTOM_SERVICES
    auto *service = new CustomAPIDeviceService<T>(name, {}, (T *) this, callback);  // NOLINT
    global_api_server->register_user_service(service);
#else
    static_assert(
        sizeof(T) == 0,
        "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
#endif
  }
#else
  template<typename T> void register_service(void (T::*callback)(), const std::string &name) {
    static_assert(
        sizeof(T) == 0,
        "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
  }
#endif
 
#ifdef USE_API_HOMEASSISTANT_STATES
  template<typename T>
  void subscribe_homeassistant_state(void (T::*callback)(StringRef), const std::string &entity_id,
                                     const std::string &attribute = "") {
    auto *obj = static_cast<T *>(this);
    global_api_server->subscribe_home_assistant_state(entity_id, optional<std::string>(attribute),
                                                      [obj, callback](StringRef state) { (obj->*callback)(state); });
  }
 
  template<typename T>
  ESPDEPRECATED("Use void callback(StringRef) instead. Will be removed in 2027.1.0.", "2026.1.0")
  void subscribe_homeassistant_state(void (T::*callback)(std::string), const std::string &entity_id,
                                     const std::string &attribute = "") {
    auto *obj = static_cast<T *>(this);
    // Explicit type to disambiguate overload resolution
    global_api_server->subscribe_home_assistant_state(
        entity_id, optional<std::string>(attribute),
        std::function<void(const std::string &)>(
            [obj, callback](const std::string &state) { (obj->*callback)(state); }));
  }
 
  template<typename T>
  void subscribe_homeassistant_state(void (T::*callback)(const std::string &, StringRef), const std::string &entity_id,
                                     const std::string &attribute = "") {
    auto *obj = static_cast<T *>(this);
    global_api_server->subscribe_home_assistant_state(
        entity_id, optional<std::string>(attribute),
        [obj, callback, entity_id](StringRef state) { (obj->*callback)(entity_id, state); });
  }
 
  template<typename T>
  ESPDEPRECATED("Use void callback(const std::string &, StringRef) instead. Will be removed in 2027.1.0.", "2026.1.0")
  void subscribe_homeassistant_state(void (T::*callback)(std::string, std::string), const std::string &entity_id,
                                     const std::string &attribute = "") {
    auto *obj = static_cast<T *>(this);
    // Explicit type to disambiguate overload resolution
    global_api_server->subscribe_home_assistant_state(
        entity_id, optional<std::string>(attribute),
        std::function<void(const std::string &)>(
            [obj, callback, entity_id](const std::string &state) { (obj->*callback)(entity_id, state); }));
  }
#else
  template<typename T>
  void subscribe_homeassistant_state(void (T::*callback)(StringRef), const std::string &entity_id,
                                     const std::string &attribute = "") {
    static_assert(sizeof(T) == 0,
                  "subscribe_homeassistant_state() requires 'homeassistant_states: true' in the 'api:' section "
                  "of your YAML configuration");
  }
 
  template<typename T>
  void subscribe_homeassistant_state(void (T::*callback)(std::string), const std::string &entity_id,
                                     const std::string &attribute = "") {
    static_assert(sizeof(T) == 0,
                  "subscribe_homeassistant_state() requires 'homeassistant_states: true' in the 'api:' section "
                  "of your YAML configuration");
  }
 
  template<typename T>
  void subscribe_homeassistant_state(void (T::*callback)(const std::string &, StringRef), const std::string &entity_id,
                                     const std::string &attribute = "") {
    static_assert(sizeof(T) == 0,
                  "subscribe_homeassistant_state() requires 'homeassistant_states: true' in the 'api:' section "
                  "of your YAML configuration");
  }
 
  template<typename T>
  void subscribe_homeassistant_state(void (T::*callback)(std::string, std::string), const std::string &entity_id,
                                     const std::string &attribute = "") {
    static_assert(sizeof(T) == 0,
                  "subscribe_homeassistant_state() requires 'homeassistant_states: true' in the 'api:' section "
                  "of your YAML configuration");
  }
#endif
 
#ifdef USE_API_HOMEASSISTANT_SERVICES
  void call_homeassistant_service(const std::string &service_name) {
    HomeassistantActionRequest resp;
    resp.service = StringRef(service_name);
    global_api_server->send_homeassistant_action(resp);
  }
 
  void call_homeassistant_service(const std::string &service_name, const std::map<std::string, std::string> &data) {
    HomeassistantActionRequest resp;
    resp.service = StringRef(service_name);
    resp.data.init(data.size());
    for (auto &it : data) {
      auto &kv = resp.data.emplace_back();
      kv.key = StringRef(it.first);
      kv.value = StringRef(it.second);  // data map lives until send completes
    }
    global_api_server->send_homeassistant_action(resp);
  }
 
  void fire_homeassistant_event(const std::string &event_name) {
    HomeassistantActionRequest resp;
    resp.service = StringRef(event_name);
    resp.is_event = true;
    global_api_server->send_homeassistant_action(resp);
  }
 
  void fire_homeassistant_event(const std::string &service_name, const std::map<std::string, std::string> &data) {
    HomeassistantActionRequest resp;
    resp.service = StringRef(service_name);
    resp.is_event = true;
    resp.data.init(data.size());
    for (auto &it : data) {
      auto &kv = resp.data.emplace_back();
      kv.key = StringRef(it.first);
      kv.value = StringRef(it.second);  // data map lives until send completes
    }
    global_api_server->send_homeassistant_action(resp);
  }
#else
  template<typename T = void> void call_homeassistant_service(const std::string &service_name) {
    static_assert(sizeof(T) == 0, "call_homeassistant_service() requires 'homeassistant_services: true' in the 'api:' "
                                  "section of your YAML configuration");
  }
 
  template<typename T = void>
  void call_homeassistant_service(const std::string &service_name, const std::map<std::string, std::string> &data) {
    static_assert(sizeof(T) == 0, "call_homeassistant_service() requires 'homeassistant_services: true' in the 'api:' "
                                  "section of your YAML configuration");
  }
 
  template<typename T = void> void fire_homeassistant_event(const std::string &event_name) {
    static_assert(sizeof(T) == 0, "fire_homeassistant_event() requires 'homeassistant_services: true' in the 'api:' "
                                  "section of your YAML configuration");
  }
 
  template<typename T = void>
  void fire_homeassistant_event(const std::string &service_name, const std::map<std::string, std::string> &data) {
    static_assert(sizeof(T) == 0, "fire_homeassistant_event() requires 'homeassistant_services: true' in the 'api:' "
                                  "section of your YAML configuration");
  }
#endif
};
 
}  // namespace esphome::api
#endif