/* SPDX-License-Identifier: GPL-2.0+ */
/*
* Copyright (C) 2007 - 2014 Red Hat, Inc.
*/
#ifndef __NETWORKMANAGER_DEVICE_FACTORY_H__
#define __NETWORKMANAGER_DEVICE_FACTORY_H__
#include "nm-dbus-interface.h"
#include "nm-device.h"
/* WARNING: this file is private API between NetworkManager and its internal
* device plugins. Its API can change at any time and is not guaranteed to be
* stable. NM and device plugins are distributed together and this API is
* not meant to enable third-party plugins.
*/
#define NM_TYPE_DEVICE_FACTORY (nm_device_factory_get_type())
#define NM_DEVICE_FACTORY(obj) \
(G_TYPE_CHECK_INSTANCE_CAST((obj), NM_TYPE_DEVICE_FACTORY, NMDeviceFactory))
#define NM_DEVICE_FACTORY_CLASS(klass) \
(G_TYPE_CHECK_CLASS_CAST((klass), NM_TYPE_DEVICE_FACTORY, NMDeviceFactoryClass))
#define NM_IS_DEVICE_FACTORY(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), NM_TYPE_DEVICE_FACTORY))
#define NM_IS_DEVICE_FACTORY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), NM_TYPE_DEVICE_FACTORY))
#define NM_DEVICE_FACTORY_GET_CLASS(obj) \
(G_TYPE_INSTANCE_GET_CLASS((obj), NM_TYPE_DEVICE_FACTORY, NMDeviceFactoryClass))
#define NM_DEVICE_FACTORY_DEVICE_ADDED "device-added"
typedef struct {
GObject parent;
} NMDeviceFactory;
typedef struct {
GObjectClass parent;
/**
* get_supported_types:
* @factory: the #NMDeviceFactory
* @out_link_types: on return, a %NM_LINK_TYPE_NONE terminated
* list of #NMLinkType that the plugin supports
* @out_setting_types: on return, a %NULL terminated list of
* base-type #NMSetting names that the plugin can create devices for
*
* Returns the #NMLinkType and #NMSetting names that this plugin
* supports. This function MUST be implemented.
*/
void (*get_supported_types)(NMDeviceFactory * factory,
const NMLinkType ** out_link_types,
const char *const **out_setting_types);
/**
* start:
* @factory: the #NMDeviceFactory
*
* Start the factory and discover any existing devices that the factory
* can manage.
*/
void (*start)(NMDeviceFactory *factory);
/**
* match_connection:
* @connection: the #NMConnection
*
* Check if the factory supports the given connection.
*/
gboolean (*match_connection)(NMDeviceFactory *factory, NMConnection *connection);
/**
* get_connection_parent:
* @factory: the #NMDeviceFactory
* @connection: the #NMConnection to return the parent name for, if supported
*
* Given a connection, returns the parent interface name, parent connection
* UUID, or parent device permanent hardware address for @connection.
*
* Returns: the parent interface name, parent connection UUID, parent
* device permanent hardware address, or %NULL
*/
const char *(*get_connection_parent)(NMDeviceFactory *factory, NMConnection *connection);
/**
* get_connection_iface:
* @factory: the #NMDeviceFactory
* @connection: the #NMConnection to return the interface name for
* @parent_iface: optional parent interface name for virtual devices
*
* Given a connection, returns the interface name that a device activating
* that connection would have.
*
* Returns: the interface name, or %NULL
*/
char *(*get_connection_iface)(NMDeviceFactory *factory,
NMConnection * connection,
const char * parent_iface);
/**
* create_device:
* @factory: the #NMDeviceFactory
* @iface: the interface name of the device
* @plink: the #NMPlatformLink if backed by a kernel device
* @connection: the #NMConnection if not backed by a kernel device
* @out_ignore: on return, %TRUE if the link should be ignored
*
* The plugin should create a new unrealized device using the details given
* by @iface and @plink or @connection. If both @iface and @plink are given,
* they are guaranteed to match. If both @iface and @connection are given,
* @iface is guaranteed to be the interface name that @connection specifies.
*
* If the plugin cannot create a #NMDevice for the link and wants the
* core to ignore it, set @out_ignore to %TRUE and return %NULL.
*
* Returns: the new unrealized #NMDevice, or %NULL
*/
NMDevice *(*create_device)(NMDeviceFactory * factory,
const char * iface,
const NMPlatformLink *plink,
NMConnection * connection,
gboolean * out_ignore);
} NMDeviceFactoryClass;
GType nm_device_factory_get_type(void);
/*****************************************************************************/
/**
* nm_device_factory_create:
* @error: an error if creation of the factory failed, or %NULL
*
* Creates a #GObject that implements the #NMDeviceFactory interface. This
* function must not emit any signals or perform any actions that would cause
* devices or components to be created immediately. Instead these should be
* deferred to the "start" interface method.
*
* Returns: the #GObject implementing #NMDeviceFactory or %NULL
*/
NMDeviceFactory *nm_device_factory_create(GError **error);
/* Should match nm_device_factory_create() */
typedef NMDeviceFactory *(*NMDeviceFactoryCreateFunc)(GError **error);
/*****************************************************************************/
const char *nm_device_factory_get_connection_parent(NMDeviceFactory *factory,
NMConnection * connection);
char *nm_device_factory_get_connection_iface(NMDeviceFactory *factory,
NMConnection * connection,
const char * parent_iface,
GError ** error);
void nm_device_factory_start(NMDeviceFactory *factory);
NMDevice *nm_device_factory_create_device(NMDeviceFactory * factory,
const char * iface,
const NMPlatformLink *plink,
NMConnection * connection,
gboolean * out_ignore,
GError ** error);
#define NM_DEVICE_FACTORY_DECLARE_LINK_TYPES(...) \
{ \
static NMLinkType const _link_types_declared[] = {__VA_ARGS__, NM_LINK_TYPE_NONE}; \
_link_types = _link_types_declared; \
}
#define NM_DEVICE_FACTORY_DECLARE_SETTING_TYPES(...) \
{ \
static const char *const _setting_types_declared[] = {__VA_ARGS__, NULL}; \
_setting_types = _setting_types_declared; \
}
#define NM_DEVICE_FACTORY_DECLARE_TYPES(...) \
static void get_supported_types(NMDeviceFactory * factory, \
const NMLinkType ** out_link_types, \
const char *const **out_setting_types) \
{ \
static NMLinkType const _link_types_null[1] = {NM_LINK_TYPE_NONE}; \
static const char *const _setting_types_null[1] = {NULL}; \
\
const NMLinkType * _link_types = _link_types_null; \
const char *const *_setting_types = _setting_types_null; \
\
{ \
__VA_ARGS__; \
} \
\
NM_SET_OUT(out_link_types, _link_types); \
NM_SET_OUT(out_setting_types, _setting_types); \
}
/**************************************************************************
* INTERNAL DEVICE FACTORY FUNCTIONS - devices provided by plugins should
* not use these functions.
**************************************************************************/
#define NM_DEVICE_FACTORY_DEFINE_INTERNAL(upper, mixed, lower, st_code, dfi_code) \
typedef struct { \
NMDeviceFactory parent; \
} NM##mixed##DeviceFactory; \
typedef struct { \
NMDeviceFactoryClass parent; \
} NM##mixed##DeviceFactoryClass; \
\
GType nm_##lower##_device_factory_get_type(void); \
\
G_DEFINE_TYPE(NM##mixed##DeviceFactory, nm_##lower##_device_factory, NM_TYPE_DEVICE_FACTORY) \
\
NM_DEVICE_FACTORY_DECLARE_TYPES(st_code) \
\
static void nm_##lower##_device_factory_init(NM##mixed##DeviceFactory *self) {} \
\
static void nm_##lower##_device_factory_class_init(NM##mixed##DeviceFactoryClass *klass) \
{ \
NMDeviceFactoryClass *factory_class = NM_DEVICE_FACTORY_CLASS(klass); \
\
factory_class->get_supported_types = get_supported_types; \
dfi_code \
}
/**************************************************************************
* PRIVATE FACTORY FUNCTIONS - for factory consumers (eg, NMManager).
**************************************************************************/
typedef void (*NMDeviceFactoryManagerFactoryFunc)(NMDeviceFactory *factory, gpointer user_data);
void nm_device_factory_manager_load_factories(NMDeviceFactoryManagerFactoryFunc callback,
gpointer user_data);
NMDeviceFactory *nm_device_factory_manager_find_factory_for_link_type(NMLinkType link_type);
NMDeviceFactory *nm_device_factory_manager_find_factory_for_connection(NMConnection *connection);
void nm_device_factory_manager_for_each_factory(NMDeviceFactoryManagerFactoryFunc callback,
gpointer user_data);
#endif /* __NETWORKMANAGER_DEVICE_FACTORY_H__ */