'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
.TH ddi_get_eventcookie 9F "6 Nov 2003" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ddi_get_eventcookie \- retrieve a NDI event service cookie handle
.SH SYNOPSIS
.LP
.nf
#include <sys/dditypes.h>
#include <sys/sunddi.h>

\fBint\fR \fBddi_get_eventcookie\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, 
     \fBddi_eventcookie_t *\fR\fIevent_cookiep\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fBdev_info_t *\fR\fIdip\fR\fR
.ad
.sp .6
.RS 4n
Child device node requesting the cookie.
.RE

.sp
.ne 2
.mk
.na
\fB\fBchar *\fR\fIname\fR\fR
.ad
.sp .6
.RS 4n
NULL-terminated string containing the name of the event.
.RE

.sp
.ne 2
.mk
.na
\fB\fBddi_eventcookie_t *\fR\fIevent_cookiep\fR\fR
.ad
.sp .6
.RS 4n
Pointer to cookie where event cookie will be returned.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_get_eventcookie()\fR function queries the device tree for a cookie matching the given event name and returns a reference to that cookie. The search is performed by a calling up the device tree hierarchy until the request is satisfied by a bus nexus driver, or the top of the \fBdev_info\fR tree is reached.
.sp
.LP
The cookie returned by this function can be used to register a callback handler, unregister a callback handler, or post an event.
.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
.rt  
Cookie handle is returned.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
.rt  
Request was not serviceable by any nexus driver in the driver's ancestral device tree hierarchy.
.RE

.SH CONTEXT
.sp
.LP
The \fBddi_get_eventcookie()\fR function can be called from user and kernel contexts only.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR
_
Interface StabilityCommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBddi_add_event_handler\fR(9F), \fBddi_remove_event_handler\fR(9F)
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR