---

dcpp.h File Reference

---

Detailed Description

#include "DitsTypes.h"
#include "DitsInteraction.h"
#include "DitsBulk.h"
#include "sds.h"
#include "arg.h"
#include "dcpp_err.h"

Go to the source code of this file.

Compounds
class	DcppBuffers
	A structure representing message buffer sizes. More...
class	DcppShared
	This is used to create and represent a shared memory segment. More...
class	DcppTransaction
	A type used to connect DcppHandler and DcppTask. More...
Typedefs
typedef void *	DcppVoidPnt
	A pointer to void.
typedef DcppVoidPnt *	DcppVoidPntPnt
	A pointer to a pointer to void.
typedef DcppHandlerRet(*	DcppHandlerRoutine )(DcppVoidPnt ClientData, StatusType *status)
	Type for call backs when messages arrive.
typedef void(*	DcppBulkTransRoutine )(unsigned long Transferred, unsigned long Total, DcppVoidPnt ClientData, StatusType *status)
	Type for call backs for DITS_REA_TRANSFERRED messages.
Enumerations
enum	DcppHandlerRet { DcppReschedule, DcppNotHandled, DcppFinished }
	Type returns by various routines to indicate what is to happen next. More...
Functions
DcppHandlerRet	DcppDispatch (StatusType *const status)
	Basic message handler function.
void	DcppUfaceCtxEnable (StatusType *const status)
	Enable handling of messages started in UFACE context.
void	DcppSpawnKickArg (DitsTransIdType transid, SdsId *id, StatusType *status)
	Create an argument structure used when kick actions which spawn.
void	DcppSpawnKickArgUpdate (DitsTransIdType transid, const SdsId *id, StatusType *status)
	Update an argument structure used when kick actions which spawn.
void	DcppForgetAll (void *client_data, int taskExit, StatusType exitStatus, StatusType *const status)
	Forget all transaction assocaited with the current action.
void	DcppVarArgsToSds (int count, Arg &ArgId, StatusType *status, va_list args)
	Convert a variable argument list into an SDS structure.
Variables
const unsigned	DcppNodeNameLen = 100
	Maximum Node name length.
const unsigned	DcppArgumentLen = 200
	Maximum Node name length.
const long int	DcppCheckData = 0x0e0e0e0e
	Internal use only.

---

Typedef Documentation

typedef void(* DcppBulkTransRoutine)(unsigned long Transferred, unsigned long Total, DcppVoidPnt ClientData, StatusType *status)

Type for call backs for DITS_REA_TRANSFERRED messages. Similar to DcppHandlerRet, but for entries with a reason of DITS_REA_TRANSFERRED only. Allow us to pass in the Transferred and Total bytes. Parameters: Transferred  Set to the number of bytes transferred so far. Total  The total number of bytes to be transferred. ClientData  Use data. status  Inherited status.

typedef DcppHandlerRet(* DcppHandlerRoutine)(DcppVoidPnt ClientData, StatusType *status)

Type for call backs when messages arrive. A type for functions which are invoked as a callback when a message comes in. Arguments of this type are used throughout the Dcpp functions. Such functions Should return either DcppReschedule is it initiated a new transactions or DcppFinished if it did not. Parameters: ClientData  user data Status  Inherited status.

typedef void* DcppVoidPnt

A pointer to void.

typedef DcppVoidPnt* DcppVoidPntPnt

A pointer to a pointer to void.

---

Enumeration Type Documentation

enum DcppHandlerRet

Type returns by various routines to indicate what is to happen next. Various routines return one of these values to indicate what the action should do. Enumeration values: DcppReschedule  More messages expected, should reschedule. DcppNotHandled  Only from DccpDisptach, message not handled. DcppFinished  Have finished, action can complete.

---

Function Documentation

DcppHandlerRet DcppDispatch (  StatusType *const    status )

Basic message handler function. This function will examine the details of a message which has caused an entry to a DRAMA reschedule handler or UFACE handler. If this message was started by DcppTask, then it will dispatch to the DcppTask to handle the message. DcppFinished/DcppReschedule is returned by DcppTask. DcppNotHandled is returned if DcppDispatch if the message was not started by DcppTask. Parameters: status  Inherited status.

void DcppForgetAll (  void *    client_data, int    taskExit, StatusType    exitStatus, StatusType *const    status )

Forget all transaction assocaited with the current action. This routine can be invoked to forget all transactions associated with the current action. This is set up such that it can be invoked as an action end routine (see DitsPutActEndRoutine()). For example: DitsPutActEndRoutine(DcppForgetAll, 0, 0, 0, status); For all Dcpp transactions, the behaviour is as if all outstanding transactions were invoked using ObeyForget() etc. This ensures the success and error routines are invoked by the orphan handler, if any. taskExit and exitStatus are ignored. This function should not be invoked by an orphan handler action and must not be invoked in uface context. Parameters: client_data  Was supplied to DitsPutActEndRoutine taskExit  Is the task exiting exitStatus  If exiting, the exit status status  Inherited status

void DcppSpawnKickArg (  DitsTransIdType    transid, SdsId *    id, StatusType *    status )

Create an argument structure used when kick actions which spawn. Actions which spawn (allowing multiple actions of the same name) must be kicked by specifing an argument structure which allows the target task to determine which invocation of the action should be kicked. This can be done by either specifing the action index (which the subsidary task can get using DitsGetActIndex()) as an argument named "KickByIndex" or anther task using the transaction id (as known by the parent action of this action), as wraped up in an argument by this call. Note, arguments to the kick itself can be added to the argument created here, using standard ArgPut functions. Also, it is possible to change the transaction id in this structure using DcppSpawnKickArgUpdate(). The Dcpp versions of these functions allow the use of SdsId's to contain the SDS ID, but otherwise just invoked the Dits versions. See also: DitsSpawnKickArg , DcppSpawnKickArgUpdate Parameters: transid  The transaction id. id  The SDS ID is returned here using SdsId::ShallowCopy (and hence deleting any old SDS ID stored here) status  Modified status.

void DcppSpawnKickArgUpdate (  DitsTransIdType    transid, const SdsId *    id, StatusType *    status )

Update an argument structure used when kick actions which spawn. Actions which spawn (allowing multiple actions of the same name) must be kicked by specifing an argument structure which allows the target task to determine which invocation of the action should be kicked. This can be done by either specifing the action index (which the subsidary task can get using DitsGetActIndex()) as an argument named "KickByIndex" or anther task using the transaction id (as known by the parent action of this action), as wraped up in an argument by this call. This routine can be used to change the transaction id in such argument structure. It can also be used to add such and item to an existing structure, which it does if it does not already exist within the structure. Note that in this case, if an item named "KickByIndex" is found, it is deleted. The add if is does not exist feature only works for internal SDS items, whilst the update only feature will also work for external SDS items. The Dcpp versions of these functions allow the use of SdsId's to contain the SDS ID, but otherwise just invoked the Dits versions. See also: DitsSpawnKickArgUopdate , DcppSpawnKickArg Parameters: transid  The transaction id. id  The SDS ID contain here is modified. If an item named KickByTransId does not exist, it will be created. The value of this item (regardless of if created) will be set to the transaction id status  Modified status.

void DcppUfaceCtxEnable (  StatusType *const    status )  [inline]

Enable handling of messages started in UFACE context. This routine allows the DcppTask routines to be invoked from Uface context. We simply specify DcppDispatch as the Uface routine, ignoring the returned value Parameters: status  Inherited status.

void DcppVarArgsToSds (  int    count, Arg &    ArgId, StatusType *    status, va_list    args )

Convert a variable argument list into an SDS structure. This function is invoked internally in Dcpp - through can be used from outside if need be. It tasks a variable argument structure and converts it to an SDS structure of the form Argumentd where d is replaced by the number of the argument Parameters: count  The number of arguments. If negative, then args contains a single character string which contains a space separated list of values arg  The values will be put into this SDS structure status  Modified status args  The variable argument list. Should be a list of character strings.

---

Variable Documentation

const unsigned DcppArgumentLen = 200

Maximum Node name length.

const long int DcppCheckData = 0x0e0e0e0e

Internal use only.

const unsigned DcppNodeNameLen = 100

Maximum Node name length.

---