/*
- * Copyright (c) 2006 Apple Computer, Inc. All Rights Reserved.
+ * Copyright (c) 2000-2004, 2012 Apple Inc. All rights reserved.
+ *
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
*
- * @APPLE_LICENSE_OSREFERENCE_HEADER_START@
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. The rights granted to you under the License
+ * may not be used to create, or enable the creation or redistribution of,
+ * unlawful or unlicensed copies of an Apple operating system, or to
+ * circumvent, violate, or enable the circumvention or violation of, any
+ * terms of an Apple operating system software license agreement.
*
- * This file contains Original Code and/or Modifications of Original Code
- * as defined in and that are subject to the Apple Public Source License
- * Version 2.0 (the 'License'). You may not use this file except in
- * compliance with the License. The rights granted to you under the
- * License may not be used to create, or enable the creation or
- * redistribution of, unlawful or unlicensed copies of an Apple operating
- * system, or to circumvent, violate, or enable the circumvention or
- * violation of, any terms of an Apple operating system software license
- * agreement.
- *
- * Please obtain a copy of the License at
- * http://www.opensource.apple.com/apsl/ and read it before using this
- * file.
- *
- * The Original Code and all software distributed under the License are
- * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
- * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
- * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
- * Please see the License for the specific language governing rights and
+ * Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this file.
+ *
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
* limitations under the License.
- *
- * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
+ *
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
*/
/*!
@header kern_control.h
*/
#define CTL_FLAG_REG_SOCK_STREAM 0x4
+#ifdef KERNEL_PRIVATE
+/*!
+ @defined CTL_FLAG_REG_EXTENDED
+ @discussion This flag indicates that this kernel control utilizes the
+ the extended fields within the kern_ctl_reg structure.
+*/
+#define CTL_FLAG_REG_EXTENDED 0x8
+#endif /* KERNEL_PRIVATE */
+
/* Data flags for controllers */
/*!
@defined CTL_DATA_NOWAKEUP
#define CTL_DATA_NOWAKEUP 0x1
/*!
@defined CTL_DATA_EOR
- @discussion The CTL_DATA_NOWAKEUP flag can be used for the enqueue
+ @discussion The CTL_DATA_EOR flag can be used for the enqueue
data and enqueue mbuf functions to mark the end of a record.
*/
#define CTL_DATA_EOR 0x2
+__BEGIN_DECLS
+
/*!
@typedef ctl_connect_func
@discussion The ctl_connect_func is used to receive
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 place for the kernel control to store a pointer to
- per-connection data.
+ @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_connect_func)(kern_ctl_ref kctlref,
struct sockaddr_ctl *sac,
disconnected from.
@param unit The unit number of the kernel control instance the client has
disconnected from.
- @param unitinfo The unitinfo value specified by the connect function
- when the client connected.
+ @param unitinfo The user-defined private data initialized by the
+ ctl_connect_func callback.
*/
typedef errno_t (*ctl_disconnect_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo);
@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 unitinfo value specified by the connect function
- when the client connected.
+ @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 chain. Your function is responsible for releasing the
mbuf chain.
@param flags The flags specified by the client when calling
send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE).
calls for the SYSPROTO_CONTROL option level.
@param kctlref The control ref of the kernel control.
@param unit The unit number of the kernel control instance.
- @param unitinfo The unitinfo value specified by the connect function
- when the client connected.
+ @param unitinfo The user-defined private data initialized by the
+ ctl_connect_func callback.
@param opt The socket option.
@param data A pointer to the socket option data. The data has
already been copied in to the kernel for you.
return an error.
@param kctlref The control ref of the kernel control.
@param unit The unit number of the kernel control instance.
- @param unitinfo The unitinfo value specified by the connect function
- when the client connected.
+ @param unitinfo The user-defined private data initialized by the
+ ctl_connect_func callback.
@param opt The socket option.
@param data A buffer to copy the results in to. May be NULL, see
discussion.
typedef errno_t (*ctl_getopt_func)(kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo,
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);
+#endif /* KERNEL_PRIVATE */
+
/*!
@struct kern_ctl_reg
@discussion This structure defines the properties of a kernel
ctl_send_func ctl_send;
ctl_setopt_func ctl_setopt;
ctl_getopt_func ctl_getopt;
+#ifdef KERNEL_PRIVATE
+ ctl_rcvd_func ctl_rcvd; /* Only valid if CTL_FLAG_REG_EXTENDED is set */
+#endif /* KERNEL_PRIVATE */
};
/*!
@param unit The unit number of the kernel control instance.
@param data A pointer to the data to send.
@param len The length of data to send.
- @param flags Send flags. CTL_DATA_NOWAKEUP is currently the only
- supported flag.
+ @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently
+ the only supported flags.
@result 0 - Data was enqueued to be read by the client.
EINVAL - Invalid parameters.
EMSGSIZE - The buffer is too large.
@param kctlref The control reference of the kernel control.
@param unit The unit number of the kernel control instance.
@param m An mbuf chain containing the data to send to the client.
- @param flags Send flags. CTL_DATA_NOWAKEUP is currently the only
- supported flag.
+ @param flags Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently
+ the only supported flags.
@result 0 - Data was enqueued to be read by the client.
EINVAL - Invalid parameters.
ENOBUFS - The queue is full.
@param kctlref The control reference of the kernel control.
@param unit The unit number of the kernel control instance.
@param space The address where to return the current space available
- @result 0 - Data was enqueued to be read by the client.
+ @result 0 - Success; the amount of space is returned to caller.
EINVAL - Invalid parameters.
*/
errno_t
ctl_getenqueuespace(kern_ctl_ref kctlref, u_int32_t unit, size_t *space);
+#ifdef KERNEL_PRIVATE
+u_int32_t ctl_id_by_name(const char *name);
+errno_t ctl_name_by_id(u_int32_t id, char *out_name, size_t maxsize);
+#endif /* KERNEL_PRIVATE */
+__END_DECLS
#endif /* KERNEL */
#endif /* KPI_KERN_CONTROL_H */
projects / apple / xnu.git / blobdiff