SYNOPSIS

#include <ggi/gcp.h>
int gcpInit(void);
int gcpExit(void);
int gcpAttach(ggi_visual_t vis);
int gcpDetach(ggi_visual_t vis);

DESCRIPTION

These are the standard LibGGI extension management functions for the LibGGIGCP extension. They allow initialization and deinitialization of the extension as a whole and of individual visuals.

gcpInit will initialize an instance of the LibGGIGCP extension and prepare it to attach to visuals.

gcpAttach, if successful, will allow LibGGIGCP functions to operate on the named visual.

gcpDetach, if successful, will clean up all resources involved in providing the named visual with the LibGGIGCP API.

gcpExit will free all resources associated with an instance of LibGGIGCP.

RETURN VALUE

gcpInit returns 0 for OK, otherwise an ggi-error(3) code.

gcpExit returns:

0

after successfully cleaning up,

>0

the number of 'open' gcpInit calls, if there has been more than one call to gcpInit. As gcpInit and gcpExit must be used in properly nested pairs, e.g. the first gcpExit after two gcpInit's will return 1.

<0

ggi-error(3), especially if more gcpExit calls have been done than gcpInit calls.

gcpAttach returns:

>=0

the number LibGGIGCP has been attached to this visual, whereas 0 means the first time.

<0

indicates an ggi-error(3).

gcpDetach returns:

0

after successfully cleaning up,

>0

the number of 'open' gcpAttach calls, if there has been more than one call to gcpAttach. As gcpAttach and gcpDetach must be used in properly nested pairs, e.g. the first gcpDetach after two gcpInit's will return 1.

<0

ggi-error(3), especially if more gcpDetach calls have been done than gcpAttach calls.

EXAMPLES

ggi_visual_t vis;
ggiInit();
gcpInit();
vis = ggiOpen(NULL);
gcpAttach(vis);
/* ... */
gcpDetach(vis);
gcpExit();
ggiExit();