- int opt, void *data, size_t *len);
-
-/*!
- @struct kern_ctl_reg
- @discussion This structure defines the properties of a kernel
- control being registered.
- @field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero).
- This string should not be empty.
- @field ctl_id The control ID may be dynamically assigned or it can be a
- 32-bit creator code assigned by DTS.
- For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set.
- For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag.
- The value of the dynamically assigned control ID is set to this field
- when the registration succeeds.
- @field ctl_unit A separate unit number to register multiple units that
- share the same control ID with DTS assigned creator code when
- the CTL_FLAG_REG_ID_UNIT flag is set.
- This field is ignored for a dynamically assigned control ID.
- @field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT.
- @field ctl_sendsize Override the default send size. If set to zero,
- the default send size will be used, and this default value
- is set to this field to be retrieved by the caller.
- @field ctl_recvsize Override the default receive size. If set to
- zero, the default receive size will be used, and this default value
- is set to this field to be retrieved by the caller.
- @field ctl_connect Specify the function to be called whenever a client
- connects to the kernel control. This field must be specified.
- @field ctl_disconnect Specify a function to be called whenever a
- client disconnects from the kernel control.
- @field ctl_send Specify a function to handle data send from the
- client to the kernel control.
- @field ctl_setopt Specify a function to handle set socket option
- operations for the kernel control.
- @field ctl_getopt Specify a function to handle get socket option
- operations for the kernel control.
-*/
-struct kern_ctl_reg
-{
+ int opt, void *data, size_t *len);
+
+#ifdef KERNEL_PRIVATE
+/*!
+ * @typedef ctl_rcvd_func
+ * @discussion The ctl_rcvd_func is called when the client reads data from
+ * the kernel control socket. The kernel control can use this callback
+ * in combination with ctl_getenqueuespace() to avoid overflowing
+ * the socket's receive buffer. When ctl_getenqueuespace() returns
+ * 0 or ctl_enqueuedata()/ctl_enqueuembuf() return ENOBUFS, the
+ * kernel control can wait until this callback is called before
+ * trying to enqueue the data again.
+ * @param kctlref The control ref of the kernel control.
+ * @param unit The unit number of the kernel control instance.
+ * @param unitinfo The user-defined private data initialized by the
+ * ctl_connect_func callback.
+ * @param flags The recv flags. See the recv(2) man page.
+ */
+typedef void (*ctl_rcvd_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo,
+ int flags);
+
+/*!
+ * @typedef ctl_send_list_func
+ * @discussion The ctl_send_list_func is used to receive data sent from
+ * the client to the kernel control.
+ * @param kctlref The control ref of the kernel control.
+ * @param unit The unit number of the kernel control instance the client has
+ * connected to.
+ * @param unitinfo The user-defined private data initialized by the
+ * ctl_connect_func callback.
+ * @param m The data sent by the client to the kernel control in an
+ * mbuf packet chain. Your function is responsible for releasing
+ * mbuf packet chain.
+ * @param flags The flags specified by the client when calling
+ * send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE).
+ */
+typedef errno_t (*ctl_send_list_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo,
+ mbuf_t m, int flags);
+
+/*!
+ * @typedef ctl_bind_func
+ * @discussion The ctl_bind_func is an optional function that allows the client
+ * to set up their unitinfo prior to connecting.
+ * @param kctlref The control ref for the kernel control the client is
+ * binding to.
+ * @param sac The address used to connect to this control. The field sc_unit
+ * contains the unit number of the kernel control instance the client is
+ * binding to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control
+ * was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure.
+ * If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was
+ * registered, sc_unit is the dynamically allocated unit number of
+ * the new kernel control instance that is used for this connection.
+ * @param unitinfo A placeholder for a pointer to the optional user-defined
+ * private data associated with this kernel control instance. This
+ * opaque info will be provided to the user when the rest of the
+ * callback routines are executed. For example, it can be used
+ * to pass a pointer to an instance-specific data structure in
+ * order for the user to keep track of the states related to this
+ * kernel control instance.
+ */
+typedef errno_t (*ctl_bind_func)(kern_ctl_ref kctlref,
+ struct sockaddr_ctl *sac,
+ void **unitinfo);
+#endif /* KERNEL_PRIVATE */
+
+/*!
+ * @struct kern_ctl_reg
+ * @discussion This structure defines the properties of a kernel
+ * control being registered.
+ * @field ctl_name A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero).
+ * This string should not be empty.
+ * @field ctl_id The control ID may be dynamically assigned or it can be a
+ * 32-bit creator code assigned by DTS.
+ * For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set.
+ * For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag.
+ * The value of the dynamically assigned control ID is set to this field
+ * when the registration succeeds.
+ * @field ctl_unit A separate unit number to register multiple units that
+ * share the same control ID with DTS assigned creator code when
+ * the CTL_FLAG_REG_ID_UNIT flag is set.
+ * This field is ignored for a dynamically assigned control ID.
+ * @field ctl_flags CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT.
+ * @field ctl_sendsize Override the default send size. If set to zero,
+ * the default send size will be used, and this default value
+ * is set to this field to be retrieved by the caller.
+ * @field ctl_recvsize Override the default receive size. If set to
+ * zero, the default receive size will be used, and this default value
+ * is set to this field to be retrieved by the caller.
+ * @field ctl_connect Specify the function to be called whenever a client
+ * connects to the kernel control. This field must be specified.
+ * @field ctl_disconnect Specify a function to be called whenever a
+ * client disconnects from the kernel control.
+ * @field ctl_send Specify a function to handle data send from the
+ * client to the kernel control.
+ * @field ctl_setopt Specify a function to handle set socket option
+ * operations for the kernel control.
+ * @field ctl_getopt Specify a function to handle get socket option
+ * operations for the kernel control.
+ */
+struct kern_ctl_reg {
projects / apple / xnu.git / blobdiff