netlink_packet_generic/
lib.rs

Help
1// SPDX-License-Identifier: MIT
2
3//! This crate provides the packet of generic netlink family and its controller.
4//!
5//! The `[GenlMessage]` provides a generic netlink family message which is
6//! sub-protocol independant.
7//! You can wrap your message into the type, then it can be used in
8//! `netlink-proto` crate.
9//!
10//! # Implementing a generic netlink family
11//! A generic netlink family contains several commands, and a version number in
12//! the header.
13//!
14//! The payload usually consists of netlink attributes, carrying the messages to
15//! the peer. In order to help you to make your payload into a valid netlink
16//! packet, this crate requires the informations about the family id,
17//! and the informations in the generic header. So, you need to implement some
18//! traits on your types.
19//!
20//! All the things in the payload including all netlink attributes used
21//! and the optional header should be handled by your implementation.
22//!
23//! ## Serializaion / Deserialization
24//! To implement your generic netlink family, you should handle the payload
25//! serialization process including its specific header (if any) and the netlink
26//! attributes.
27//!
28//! To achieve this, you should implement [`netlink_packet_utils::Emitable`]
29//! trait for the payload type.
30//!
31//! For deserialization, [`netlink_packet_utils::ParseableParametrized<[u8],
32//! GenlHeader>`](netlink_packet_utils::ParseableParametrized) trait should be
33//! implemented. As mention above, to provide more scalability, we use the
34//! simplest buffer type: `[u8]` here. You can turn it into other buffer type
35//! easily during deserializing.
36//!
37//! ## `GenlFamily` trait
38//! The trait is aim to provide some necessary informations in order to build
39//! the packet headers of netlink (nlmsghdr) and generic netlink (genlmsghdr).
40//!
41//! ### `family_name()`
42//! The method let the resolver to obtain the name registered in the kernel.
43//!
44//! ### `family_id()`
45//! Few netlink family has static family ID (e.g. controller). The method is
46//! mainly used to let those family to return their familt ID.
47//!
48//! If you don't know what is this, please **DO NOT** implement this method.
49//! Since the default implementation return `GENL_ID_GENERATE`, which means
50//! the family ID is allocated by the kernel dynamically.
51//!
52//! ### `command()`
53//! This method tells the generic netlink command id of the packet
54//! The return value is used to fill the `cmd` field in the generic netlink
55//! header.
56//!
57//! ### `version()`
58//! This method return the family version of the payload.
59//! The return value is used to fill the `version` field in the generic netlink
60//! header.
61//!
62//! ## Family Header
63//! Few family would use a family specific message header. For simplification
64//! and scalability, this crate treats it as a part of the payload, and make
65//! implementations to handle the header by themselves.
66//!
67//! If you are implementing such a generic family, note that you should define
68//! the header data structure in your payload type and handle the serialization.
69
70#[macro_use]
71extern crate netlink_packet_utils;
72
73pub mod buffer;
74pub use self::buffer::GenlBuffer;
75
76pub mod constants;
77
78pub mod ctrl;
79
80pub mod header;
81pub use self::header::GenlHeader;
82
83pub mod message;
84pub use self::message::GenlMessage;
85
86pub mod traits;
87pub use self::traits::GenlFamily;
netlink_packet_generic/lib.rs

netlink_packet_generic/
lib.rs
