summaryrefslogtreecommitdiff
path: root/doc/C-API.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/C-API.txt')
-rw-r--r--doc/C-API.txt198
1 files changed, 0 insertions, 198 deletions
diff --git a/doc/C-API.txt b/doc/C-API.txt
deleted file mode 100644
index edf0d56..0000000
--- a/doc/C-API.txt
+++ /dev/null
@@ -1,198 +0,0 @@
-==============================================================================
- Description of C API bindings
-==============================================================================
-
-This file contains information specific to the C bindings. Refer to the generic
-API documentation for information that is not specific to C bindings. See also
-C-HOWTO.txt .
-
-
-
-
-Data types
-==========
-
-
-C allows only a limited set of data types. Types from the abstract API that
-are not available in C are used as follows:
-
-bool - int with values 1 for true and 0 for false
-
-string - char* NUL-terminated string; calls that return char* allocate it dynamically
-and the caller must deallocate it by calling free()
-
-arrays ( int[], string[] ) - intarr, stringarr (see below)
-
-windowinfo - DapiWindowInfo (see below)
-
-
-DapiConnection
---------------
-
-Opaque data type that contains all internal data. Most calls require it
-as the first argument.
-
-
-DapiWindowInfo
---------------
-
-Some call require information about a window related to the call. This structure
-holds data about such window. Call dapi_windowInfoInitWindow() to fill in the info
-or use the convenience _Window functions.
-
-
-void dapi_windowInfoInitWindow( DapiWindowInfo* winfo, long window )
---------------------------------------------------------------------
-
-Initializes DapiWindowInfo with data about given window.
-
-winfo: DapiWindowInfo data structure to initialize
-window: Window handle (as used with X Window System)
-
-
-void dapi_freeWindowInfo( DapiWindowInfo winfo )
-------------------------------------------------
-
-Frees DapiWindowInfo structure data.
-
-winfo: DapiWindowInfo data structure to free data from.
-
-
-intarr
-------
-
-A structure representing an integer array.
-typedef struct
- {
- int count;
- int* data;
- } intarr;
-'count' is number of elements, 'data' is array of elements.
-
-
-void dapi_freeintarr( intarr arr )
-----------------------------------
-
-Convenience function that frees dynamically allocated data from intarr.
-All DAPI functions that return intarr allocate the data dynamically
-and the caller must free it.
-
-
-stringarr
----------
-
-A structure representing a string array.
-typedef struct
- {
- int count;
- char** data;
- } stringarr;
-'count' is number of elements, 'data' is array of char* strings.
-
-
-void dapi_freestringarr( stringarr arr )
-----------------------------------------
-
-Convenience function that frees dynamically allocated data from stringarr.
-All DAPI functions that return stringarr allocate the data dynamically
-and the caller must free it.
-
-
-
-
-
-
-Utility functions
-=================
-
-
-DapiConnection* dapi_connect( void )
-------------------------------------
-
-Tries to connect to a running backend daemon.
-
-Returns: NULL if failed, opaque connection handle if success.
-
-
-DapiConnection* dapi_connectAndInit( void )
--------------------------------------------
-
-Convenience function that calls dapi_connect() and if successful
-also performs initialization by calling dapi_Init() (see later).
-
-
-void dapi_close( DapiConnection* conn )
----------------------------------------
-
-Closes a connection to a backend daemon.
-
-conn: Opaque connection handle.
-
-
-int dapi_socket( DapiConnection* conn )
----------------------------------------
-
-Returns a file descriptor that can be used with system functions such as select()
-to watch activity.
-
-conn: Opaque connection handle.
-Returns: file descriptor
-
-
-void dapi_processData( DapiConnection* conn )
----------------------------------------------
-
-Processes pending incoming data on the connection socket.
-
-conn: Opaque connection handle.
-
-
-int dapi_readCommand( DapiConnection* conn, int* comm, int* seq )
------------------------------------------------------------------
-
-Reads a command header of the next incoming command request/reply.
-
-conn: Opaque connection handle.
-comm: Id number of the incomming command.
-seq: Sequence number of the incoming command.
-Returns: 1 if successful, 0 if failure
-
-
-TBD:
-typedef void (*DapiGenericCallback)( DapiConnection* conn, int command, int seq );
-DapiGenericCallback dapi_setGenericCallback( DapiConnection* conn, DapiGenericCallback callback );
-void dapi_genericCallback( DapiConnection* conn, int command, int seq );
-
-
-
-
-
-
-Calls functions
-===============
-
-
-There are several ways to invoke the API calls. For call XYZ there is:
-
-- lowlevel dapi_writeCommandXYZ(), dapi_readReplyXYZ() calls that write a command
- request resp. read a command reply.
-
- dapi_writeCommandXYZ() writes a command header and all command arguments and
- returns either 0 if failure or sequence number of the command. Each command request
- has a specific sequence number assigned and is used to identify replies.
-
- dapi_readCommandXYZ() reads all reply arguments. It doesn't read command header,
- dapi_readCommand() must be called first to identify a command. Returns 1 if success
- or 0 if failure.
-
- Include file dapi/comm_generated.h contains all function prototypes.
-
-- blocking dapi_XYZ() call that writes a command request and waits for a reply.
- Include file dapi/calls_generated.h contains all function prototypes.
-
-- non-blocking dapi_callbackXYZ() call that writes a command and invokes the passed
- callback when a reply comes.
-
- dapi_callbackXYZ() returns a sequence number if success or 0 if failure
-
- Include file dapi/callbacks_generated.h contains all function prototypes.