SENSE Client API Specification

V0.10 RBLandau 19960519

[[Outline only at this time, sorry. Some details will be given just to spark discussion, but information in this section is highly subject to change without notice.]]


Introduction and Overview

Motivation

the usual goals, crib from Jay's overview and faqs

dynamic registration

reliable delivery

adjustable fan-out

Basic Terminology

Properties

Methods

States

Order of Operations

Protocol Examples

Code Examples


Interface Overview

Programming Considerations

Binding to a Server

Calling Conventions


Key Data Structures

Data Types

String

Enumerated Types

[[tbs]]

Data Structures

ServerContext

PropertyList

NameList

[[tbs]]

Message Formats

The Minimal Event Message Wrapper


Client Interface

Initialization Functions

Before any communication is possible, a Client must establish a context with a Server. The Client specifies some network addressing information to enable the API library to find the Server.

A Client can keep multiple Server contexts open simultaneously.

ServerOpen( 
	char*		in_ServerAddr, 
	sfSENSECLI*	outp_ServerContext 
)

A Client should close the Server context at the end of a session.

ServerClose( 
	sfSENSECLI*	inp_ServerContext
)


Transient Listing Functions

To retrieve the set of objects of some class, a Client uses these iteration functions. The GetFirst - GetNext pairs are intended to fit well with for-loops in most languages.

ObjectGetFirst( 
	int		in_ServerContext, 
	int*		outp_CollectionHandle, 
	int		in_nClass, 
	sfPropList_t *	inoutp_PropertyList 
)

ObjectGetNext( 
	int		in_ServerContext, 
	int*		inoutp_CollectionHandle, 
	int		in_nClass, 
	sfPropList_t *	inoutp_PropertyList 
)

Notes:

If the caller terminates the loop before the last item is retrieved, the caller must close the collection to free resources.

ObjectCloseCollection( 
	int		in_CollectionHandle 
)

Since Publications can be of a number of different classes, a separate function is provided to retrieve all Publications in a Server.

Publications are only a small portion of the total object instances in an active Server; Editions, Clients, and Subscriptions are all generally more numerous. A Client that wishes to enumerate all of the network entities that publish their status through SENSE should get Publication Ids, Names, Classes, etc., using this mechanism.

PublicationGetFirst( 
	int		in_ServerContext, 
	int*		outp_CollectionHandle, 
	sfPropList_t*	inoutp_PropertyList 
)
PublicationGetNext( 
	int		in_ServerContext, 
	int*		inoutp_CollectionHandle, 
	sfPropList_t*	inoutp_PropertyList 
)

The Client may retrieve properties for any object at any time. The identifier needed to specify the object within the server is the Id.Id property of the object.

A Client may retrieve only a few properties for a large class of objects in a preliminary scan, then retrieve additional properties for a few objects of interest. The Client must retrieve the Id.Id property of the objects during the first loop to enable it to access the same objects again for more details.

ObjectGetProperties( 
	int		in_ServerContext, 
	int		in_nObjectId, 
	sfPropList_t*	inoutp_PropertyList 
)

Procedure

Very approximate swag pseudocode for Client to subscribe to an Edition:

for (/* all Publications of the correct class */
	Id.Class="/Sense/Printer", 
	Id.Id,		/* Server returns output values */
	Edition.IdList,	/*  for all properties          */ 
	Id.Name, 
	Id.Host.Name, 
	Id.Host.Address
	) 
{
	/* determine if this is the Publication we want */
	/* . . . */

	for (/* all Editions of that Publication */
		Id.Class="/Sense/Edition",
		Id.Id=<extracted from Edition.IdList
			for Publication>, 
		Id.Name
	)
	{
		/* is this the Edition we want? */
		if (	Id.Name=="Minimal" )
		{
			/* subscribe */
		}
	}
}


Registration Functions

[[From here to end of this section, names of functions are included only as placeholders. Argument lists are fragmentary, usually indicated by ungrammatical structure.]]

ClientRegister( 
	int		in_ServerContext, 
)

ClientUnregister( 
	int		in_ServerContext, 
)


Publisher Functions

PublicationRegister( 
	int		in_ServerContext, 
)

PublicationUnregister( 
	int		in_ServerContext, 
)

EditionRegister( 
	int		in_ServerContext, 
)

EditionUnregister( 
	int		in_ServerContext, 
)

EventOriginate( 
	int		in_ServerContext, 
)

ObjectUpdateProperties( 
	int		in_ServerContext, 
)


Subscriber Functions

dunno yet

Subscribe(
	int		in_ServerContext, 
)

Unsubscribe(
	int		in_ServerContext, 
)

EventReceive( 	
			in_ServerContext, 
			inp_szBuffer 
)


Maintenance (Diagnostic) Functions

KeepAlive(

Loopback(


Manager Functions

In general, management operations and management properties of Servers are implementation-dependent.

ServerGetProperties( 
	int		in_ServerContext, 
	sfPropList_t*	inoutp_PropertyList 
)

ServerSetProperties(
	int		in_ServerContext, 
	sfPropList_t*	inoutp_PropertyList 
)

To manage operation of the Server. Some changes in properties, for instance network configuration, may not take effect until the Server has been restarted.

ServerStart(
	int		in_ServerContext, 
)
ServerStop(
	int		in_ServerContext, 
)
ServerGetConfiguration(
	int		in_ServerContext, 
)  (from file)
ServerSaveConfiguration(
	int		in_ServerContext, 
)  (to file)
PublicationDelete(
	int		in_ServerContext, 
)
SubscriptionDelete(
	int		in_ServerContext, 
)
EditionDelete(
	int		in_ServerContext, 
)
ClientDelete(
	int		in_ServerContext, 
)


Client Data Structure Support Interface

Property List Functions

ProplistCreate( )
ProplistAddProperty( )
ProplistRemoveProperty( )
ProplistGetValue( )
ProplistPutValue( )
ProplistReleaseValue( )
ProplistReleaseAllValues( )
ProplistReleaseAll( )

Name List Functions

[[tbs]]

Event Functions

[[tbs]]


Copyright (C) 1996 by Richard Landau & Jay Martin. All rights reserved.
Comments and flames to the authors. "Why use rational argument when there's a flamethrower handy?" Hey, go ahead. We didn't exactly leave the gloves on when we wrote this. Richard Landau (landau@hannah.enet.dec.com) & Jay Martin (jkm@underscore.com) using that sterling tool, HTML Author. Last modified 96/05/19.