share/man/man9f/ldi_ev_get_cookie.9f

   1 '\" te
   2 .\"  Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH LDI_EV_GET_COOKIE 9F "Aug 21, 2007"
   7 .SH NAME
   8 ldi_ev_get_cookie \- get an LDI event cookie for a specified event
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/sunldi.h>
  13
  14 \fBint\fR \fBldi_ev_get_cookie\fR(\fIldi_handle_t lh\fR, \fIchar *evname\fR,
  15      \fIldi_ev_cookie_t *cookiep\fR);
  16 .fi
  17
  18 .SH INTERFACE LEVEL
  19 .sp
  20 .LP
  21 Solaris DDI specific (Solaris DDI)
  22 .SH PARAMETERS
  23 .sp
  24 .ne 2
  25 .na
  26 \fB\fIldi_handle_t lh\fR\fR
  27 .ad
  28 .sp .6
  29 .RS 4n
  30 A layered handle representing the device for which the event notification was
  31 requested.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIchar *evname\fR\fR
  38 .ad
  39 .sp .6
  40 .RS 4n
  41 The string name of the event.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIldi_ev_cookie_t *cookiep\fR\fR
  48 .ad
  49 .sp .6
  50 .RS 4n
  51 A pointer to type \fBldi_ev_cookie_t\fR. Contains a pointer to the event cookie
  52 on return.
  53 .RE
  54
  55 .SH DESCRIPTION
  56 .sp
  57 .LP
  58 The \fBldi_ev_get_cookie()\fR function accepts the string name of a state
  59 change event affecting the device represented by the layered driver handle
  60 "\fBlh\fR" and returns an opaque cookie on success. The call is successful if
  61 the framework supports event notification for the event named by
  62 "\fBevname\fR". If successful, the function returns an opaque cookie through
  63 the "\fBcookiep\fR" parameter. The cookie is required in subsequent calls for
  64 registering callbacks on events.
  65 .sp
  66 .LP
  67 The following two LDI events are currently defined:
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fBLDI_EV_OFFLINE\fR\fR
  72 .ad
  73 .sp .6
  74 .RS 4n
  75 The device is moving to the offline state.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBLDI_EV_DEGRADE\fR\fR
  82 .ad
  83 .sp .6
  84 .RS 4n
  85 The device is moving to the degraded state.
  86 .RE
  87
  88 .sp
  89 .LP
  90 \fBldi_ev_get_cookie()\fR also accepts the string name of any events defined
  91 for NDI event services. For such events, \fBldi_ev_get_cookie()\fR replaces
  92 \fBldi_get_eventcookie\fR(9F) (which is now obsolete).
  93 .SH RETURN VALUES
  94 .sp
  95 .LP
  96 The return values for this function are:
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBLDI_EV_SUCCESS\fR\fR
 101 .ad
 102 .sp .6
 103 .RS 4n
 104 The event cookie was created successfully.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBLDI_EV_FAILURE\fR\fR
 111 .ad
 112 .sp .6
 113 .RS 4n
 114 An error occurred and the cookie was not created.
 115 .RE
 116
 117 .SH CONTEXT
 118 .sp
 119 .LP
 120 This function can be called from user and kernel contexts only.
 121 .SH SEE ALSO
 122 .sp
 123 .LP
 124 \fBldi_ev_register_callbacks\fR(9F), \fBldi_ev_remove_callbacks\fR(9F)