Programming with the wftk: sessions

Programmer's Guide to the wftk: working with sessions

[ wftk documentation home ] [ wftk programmer's guide home ]

Sessions

Sessions are unfortunately one place where my thinking was caught in flux. I originally started designing the API on a stateless, sessionless model, then realized I wanted to be able to cache things like datasheets so they didn't have to be loaded from disk for each operation. So I started putting a session parameter in every call, but with guards, so that given a NULL session handle, the API would still Do the Right Thing (i.e. act stateless). Then I realized that the session was the only place to hang configuration, at which point I threw up my hands and decided a session was probably required for all access to the wftk. Maybe it's not, and you can still get away with a NULL session handle if all your parameters are compiled in, but don't blame me if it doesn't work, because I haven't tested it and frankly doubt you'll get three steps in.

All that was by way of saying, sorry for the ambivalence about sessions. They're really useful.

Functions

void * wftk_session_alloc      ();
void   wftk_session_free       (void * session);
void   wftk_session_current    (void * session, XML * object);
void   wftk_session_configure  (void * session, XML * config);
void   wftk_session_setuser    (void * session, char * userid);
XML  * wftk_session_getuser    (void * session);
XML  * wftk_session_stashvalue (void * session, const char * value);
void   wftk_session_freevalue  (void * session, const char * value);
XML  * wftk_session_cache      (void * session, XML * key, int * found);
XML  * wftk_session_cachecheck (void * session, XML * key);

Details

wftk_session_alloc returns void *

The wftk_session_alloc simply allocates a fresh wftk session. You must free the session with wftk_session_free.

wftk_session_free returns nothing

void * session

The wftk_session_alloc frees a session object and cleans up any associated configuration, cached objects, and stashed values it may have.

wftk_session_current returns nothing

void * session,
XML * object

Sets the given object as the "current" member of its class. This function should be considered deprecated, as it was an initial stab at caching. I don't think it makes a lot of sense at this point.

wftk_session_configure returns nothing

void * session,
XML * config

Sets the given XML as the configuration structure for the session. The configuration structure is used by the internal library and by adaptors to retrieve various named values for the session. Eventually we need to document those.

wftk_session_setuser returns nothing

void * session,
const char * userid

Sets the given userid as the current user of the session. This value will be used by the permissions database to determine permission levels, will be used as the "Requestor" role in processes started via action, and will be used to look up user information for wftk_session_getuser.

wftk_session_getuser returns XML *

void * session

Returns an XML user structure encoding everything wftk knows about the current user. This is pretty much limited to the userid and contact information at this point.

wftk_session_stashvalue returns XML *

void * session,
const char * value

Stashes a string value so that the heap manager (such as it is) can clean it up when the session is killed. The other benefit to this is that duplicated values can be managed together; if a value is already in the stash, then the same XML will be returned. This saves a lot of hassle about who should do the freeing of malloc'd strings. The XML returned is in the form of <value value="(string)">, where "(string)" is of course the value you supply.

wftk_session_freevalue returns nothing

void * session,
const char * value

If you want to avoid growing your session value stash, you can suggest that the session free your value when you know you're done with it. This decrements a reference count; values won't be freed if somebody else was using them. The values will all be freed when you free the session anyway, but if you have a long-term session this might come in handy.

wftk_session_cache returns XML *

void * session,
XML * key,
int * found

The object cache is another useful feature of the session. The way you use it is simple. If you have the type (element name) and id (id attribute) of an object, you can create XML to that effect. An example would be <datasheet id="48">. Supply this "key" object to the cache, and if the object is found, your key will be freed and the cached version will be returned. If the object isn't cached, then the key will be kept in the cache (just in case it's a full object) and also returned. The "found" parameter can be used to signal whether the returned value is the original key or not; in many cases you won't care, so if this parameter is NULL, the function won't fail.

wftk_session_cachecheck returns XML *

void * session,
XML * key

The wftk_session_cachecheck function never adds anything to the cache. It returns NULL if the given key doesn't find anything in the cache.