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:

• Caller provides PropertyList containing names and some values. Value of Id.Class property can be used to restrict search. Server returns all requested property values, as possible, for instances found.
• Multiple looping contexts can be open simultaneously. Generally, one would expect them to be strictly nested, but that is not required.
• Class = publisher, edition, server.
• Class = subscription, client, also, on implementations that permit management access to client information. Access to these classes may require security authentication.
• Class = "*" wildcard will retrieve instances of all object classes in the Server.
• CollectionHandle is returned to the caller by the GetFirst call, used by the caller on all subsequent calls, including the CloseCollection call, if one is necessary to terminate the loop.
• CollectionHandle = NULL on return means end of collection, or no such collection if returned on the GetFirst call.

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 
)

• Property name wildcard * permitted to get complete list of property names on all these functions? [[Needs careful design: requires that caller clean up prop list completely, never reuse, I think.]]

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]]