envoy_services

Index

AddService()	FindServiceA()	FindServiceByName()	GetServiceAttrsA()
LockServiceList()	LoseService()	MarkServiceTemp()	NextService()
SetServiceAttrsA()	UnlockServiceList()

AddService()

Synopsis

BOOL AddService(
         CONST_STRPTR name,
         CONST_STRPTR path,
         struct TagItem * tagList );

BOOL AddServiceTags(
         CONST_STRPTR name,
         CONST_STRPTR path,
         TAG tag, ... );

Function

Append a service to the list: name, library path and the attributes
of SetServiceAttrsA(). The node is never temporary on return. Locks
the list itself.

Result

TRUE on success.

FindServiceA()

Synopsis

struct Entity * FindServiceA(
         CONST_STRPTR remoteHost,
         CONST_STRPTR serviceName,
         struct Entity * srcEntity,
         struct TagItem * tagList );

struct Entity * FindService(
         CONST_STRPTR remoteHost,
         CONST_STRPTR serviceName,
         struct Entity * srcEntity,
         TAG tag, ... );

Function

Connect to a service: ask the Services Manager of remoteHost (NULL
for this machine) to start serviceName for the user given by the
tags, then FindEntity() the entity it names, from srcEntity.

Inputs

remoteHost  - host name, or NULL for the local host
serviceName - name of the service as configured on that host
srcEntity   - the caller's entity; the returned link belongs to it
tagList     - FSVC_UserName (STRPTR), FSVC_PassWord (STRPTR),
              FSVC_Error (ULONG *)

Result

The connected entity, or NULL. On failure the ULONG pointed to by
FSVC_Error receives: the FindEntity() error if the Services Manager
could not be reached (521/522/523), the Services Manager's reply
(560 unknown service, 561 service library cannot be opened, 562 bad
request, or the service's own StartServiceA() error), the error of
the final FindEntity(), or 501 for a resource failure.

Notes

Every successful call needs a LoseService().

FindServiceByName()

Synopsis

struct ServiceNode * FindServiceByName(
         CONST_STRPTR name );

Function

Case-insensitive lookup of a non-temporary node. The list must be
locked.

GetServiceAttrsA()

Synopsis

void GetServiceAttrsA(
         struct ServiceNode * node,
         struct TagItem * tagList );

void GetServiceAttrs(
         struct ServiceNode * node,
         TAG tag, ... );

Function

Read attributes of a node: SVCL_Flags, SVCL_Name, SVCL_Path,
SVCL_Active, SVCL_Temp. ti_Data points to the IPTR receiving the
value; string pointers stay valid while the list is locked.

LockServiceList()

Synopsis

struct ServiceNode * LockServiceList();

Function

Lock the service list and return its first node, or NULL when it is
empty. Every call needs an UnlockServiceList().

LoseService()

Synopsis

void LoseService(
         struct Entity * entity );

Function

Give up an entity obtained from FindServiceA().

MarkServiceTemp()

Synopsis

void MarkServiceTemp(
         struct ServiceNode * node );

Function

Mark a node for release by the next UnlockServiceList(); it is no
longer found or iterated. The list must be locked.

NextService()

Synopsis

struct ServiceNode * NextService(
         struct ServiceNode * node );

Function

The node after node, skipping temporary ones; NULL at the end.

SetServiceAttrsA()

Synopsis

void SetServiceAttrsA(
         struct ServiceNode * node,
         struct TagItem * tagList );

void SetServiceAttrs(
         struct ServiceNode * node,
         TAG tag, ... );

Function

Change attributes of a node: SVCL_Flags (ULONG), SVCL_Active (BOOL),
SVCL_Temp (BOOL). The list must be locked.

UnlockServiceList()

Synopsis

void UnlockServiceList();

Function

Release nodes marked with MarkServiceTemp(), then unlock the list.