ds.h revision 1991:f29baf5bf770 
1/*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21
22/*
23 * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
24 * Use is subject to license terms.
25 */
26
27#ifndef _DS_H
28#define	_DS_H
29
30#pragma ident	"%Z%%M%	%I%	%E% SMI"
31
32/*
33 * Domain Services Client Interface
34 */
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40typedef uint64_t	ds_svc_hdl_t;	/* opaque service handle */
41typedef void		*ds_cb_arg_t;	/* client specified callback arg */
42
43#define	DS_INVALID_HDL	(0)		/* a ds handle cannot be zero */
44
45/*
46 * Domain Services Versioning
47 */
48typedef struct ds_ver {
49	uint16_t	major;
50	uint16_t	minor;
51} ds_ver_t;
52
53/*
54 * Domain Services Capability
55 *
56 * A DS capability is exported by a client using a unique service
57 * identifier string. Along with this identifier is the list of
58 * versions of the capability that the client supports.
59 */
60typedef struct ds_capability {
61	char		*svc_id;	/* service identifier */
62	ds_ver_t	*vers;		/* list of supported versions */
63	int		nvers;		/* number of supported versions */
64} ds_capability_t;
65
66/*
67 * Domain Services Client Event Callbacks
68 *
69 * A client implementing a DS capability provides a set of callbacks
70 * when it registers with the DS framework. The use of these callbacks
71 * is described below:
72 *
73 *    ds_reg_cb(ds_cb_arg_t arg, ds_ver_t *ver, ds_svc_hdl_t hdl)
74 *
75 *	    The ds_reg_cb() callback is invoked when the DS framework
76 *	    has successfully completed version negotiation with the
77 *	    remote endpoint for the capability. It provides the client
78 *	    with the negotiated version and a handle to use when sending
79 *	    data.
80 *
81 *    ds_unreg_cb(ds_cb_arg_t arg)
82 *
83 *	    The ds_unreg_cb() callback is invoked when the DS framework
84 *	    detects an event that causes the registered capability to
85 *	    become unavailable. This includes an explicit unregister
86 *	    message, a failure in the underlying communication transport,
87 *	    etc. Any such event invalidates the service handle that was
88 *	    received from the register callback.
89 *
90 *    ds_data_cb(ds_cb_arg_t arg, void *buf, size_t buflen)
91 *
92 *	    The ds_data_cb() callback is invoked whenever there is an
93 *	    incoming data message for the client to process. It provides
94 *	    the contents of the message along with the message length.
95 */
96typedef struct ds_clnt_ops {
97	void (*ds_reg_cb)(ds_cb_arg_t arg, ds_ver_t *ver, ds_svc_hdl_t hdl);
98	void (*ds_unreg_cb)(ds_cb_arg_t arg);
99	void (*ds_data_cb)(ds_cb_arg_t arg, void *buf, size_t buflen);
100	ds_cb_arg_t cb_arg;
101} ds_clnt_ops_t;
102
103/*
104 * Domain Services Capability Interface
105 */
106extern int ds_cap_init(ds_capability_t *cap, ds_clnt_ops_t *ops);
107extern int ds_cap_fini(ds_capability_t *cap);
108extern int ds_cap_send(ds_svc_hdl_t hdl, void *buf, size_t buflen);
109
110#ifdef __cplusplus
111}
112#endif
113
114#endif /* _DS_H */
115