ds.h revision 1ae0874509b6811fdde1dfd46f0d93fd09867a3f
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * CDDL HEADER START
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * The contents of this file are subject to the terms of the
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * Common Development and Distribution License (the "License").
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * You may not use this file except in compliance with the License.
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * See the License for the specific language governing permissions
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * and limitations under the License.
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * When distributing Covered Code, include this CDDL HEADER in each
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * If applicable, add the following below this CDDL HEADER, with the
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * fields enclosed by brackets "[]" replaced with your own identifying
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * information: Portions Copyright [yyyy] [name of copyright owner]
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * CDDL HEADER END
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * Use is subject to license terms.
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo#pragma ident "%Z%%M% %I% %E% SMI"
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * Domain Services Client Interface
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppoextern "C" {
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppotypedef uint64_t ds_svc_hdl_t; /* opaque service handle */
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppotypedef void *ds_cb_arg_t; /* client specified callback arg */
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo#define DS_INVALID_HDL (0) /* a ds handle cannot be zero */
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * Domain Services Versioning
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppotypedef struct ds_ver {
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * Domain Services Capability
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * A DS capability is exported by a client using a unique service
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * identifier string. Along with this identifier is the list of
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * versions of the capability that the client supports.
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppotypedef struct ds_capability {
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * Domain Services Client Event Callbacks
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * A client implementing a DS capability provides a set of callbacks
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * when it registers with the DS framework. The use of these callbacks
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * is described below:
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * ds_reg_cb(ds_cb_arg_t arg, ds_ver_t *ver, ds_svc_hdl_t hdl)
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * The ds_reg_cb() callback is invoked when the DS framework
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * has successfully completed version negotiation with the
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * remote endpoint for the capability. It provides the client
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * with the negotiated version and a handle to use when sending
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * ds_unreg_cb(ds_cb_arg_t arg)
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * The ds_unreg_cb() callback is invoked when the DS framework
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * detects an event that causes the registered capability to
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * become unavailable. This includes an explicit unregister
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * message, a failure in the underlying communication transport,
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * etc. Any such event invalidates the service handle that was
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * received from the register callback.
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * ds_data_cb(ds_cb_arg_t arg, void *buf, size_t buflen)
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * The ds_data_cb() callback is invoked whenever there is an
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * incoming data message for the client to process. It provides
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * the contents of the message along with the message length.
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppotypedef struct ds_clnt_ops {
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo void (*ds_reg_cb)(ds_cb_arg_t arg, ds_ver_t *ver, ds_svc_hdl_t hdl);
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo void (*ds_data_cb)(ds_cb_arg_t arg, void *buf, size_t buflen);
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo * Domain Services Capability Interface
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppoextern int ds_cap_init(ds_capability_t *cap, ds_clnt_ops_t *ops);
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppoextern int ds_cap_send(ds_svc_hdl_t hdl, void *buf, size_t buflen);
1ae0874509b6811fdde1dfd46f0d93fd09867a3fheppo#endif /* _DS_H */