#ifndef _NORM_API #define _NORM_API /******************************************************************************* * NOTE: To use NORM as a DLL on Win32 platforms, the macro "NORM_USE_DLL" must be * defined. Otherwise, the static library "NormLib.lib" is built and should * be used for your code compilation and linking. ********************************************************************************/ #ifdef WIN32 #include #include #ifdef NORM_USE_DLL #ifdef _NORM_API_BUILD #define NORM_API_LINKAGE __declspec(dllexport) // to support building of "Norm.dll" #else #define NORM_API_LINKAGE __declspec(dllimport) // to let apps use "Norm.dll" functions #endif // if/else _NORM_API_BUILD #else #define NORM_API_LINKAGE #endif // if/else NORM_USE_DLL #else #include // for "off_t" #define NORM_API_LINKAGE #endif // if/else WIN32/UNIX //////////////////////////////////////////////////////////// // IMPORTANT NOTICE // The NORM API is _very_ much in a developmental phase // right now. So, although this code is available in // source code distribution, it is very much subject // to change in future revisions. The goal of the NORM // API _will_ be to provide a stable base of function calls // for applications to use, even as the underlying NORM // C++ code continues to evolve. But, until this notice // is removed, the API shouldn't be considered final. /** NORM API Types */ typedef const void* NormInstanceHandle; extern NORM_API_LINKAGE const NormInstanceHandle NORM_INSTANCE_INVALID; typedef const void* NormSessionHandle; extern NORM_API_LINKAGE const NormSessionHandle NORM_SESSION_INVALID; typedef unsigned short NormSessionId; typedef const void* NormNodeHandle; extern NORM_API_LINKAGE const NormNodeHandle NORM_NODE_INVALID; typedef unsigned long NormNodeId; extern NORM_API_LINKAGE const NormNodeId NORM_NODE_NONE; extern NORM_API_LINKAGE const NormNodeId NORM_NODE_ANY; typedef const void* NormObjectHandle; extern NORM_API_LINKAGE const NormObjectHandle NORM_OBJECT_INVALID; typedef unsigned short NormObjectTransportId; #ifdef WIN32 typedef __int64 NormSize; #else typedef off_t NormSize; #endif // WIN32 NORM_API_LINKAGE enum NormObjectType { NORM_OBJECT_NONE, NORM_OBJECT_DATA, NORM_OBJECT_FILE, NORM_OBJECT_STREAM }; NORM_API_LINKAGE enum NormFlushMode { NORM_FLUSH_NONE, NORM_FLUSH_PASSIVE, NORM_FLUSH_ACTIVE }; NORM_API_LINKAGE enum NormNackingMode { NORM_NACK_NONE, NORM_NACK_INFO_ONLY, NORM_NACK_NORMAL }; NORM_API_LINKAGE enum NormAckingStatus { NORM_ACK_INVALID, NORM_ACK_FAILURE, NORM_ACK_PENDING, NORM_ACK_SUCCESS }; NORM_API_LINKAGE enum NormProbingMode { NORM_PROBE_NONE, NORM_PROBE_PASSIVE, NORM_PROBE_ACTIVE }; NORM_API_LINKAGE enum NormRepairBoundary { NORM_BOUNDARY_BLOCK, NORM_BOUNDARY_OBJECT }; NORM_API_LINKAGE enum NormEventType { NORM_EVENT_INVALID = 0, NORM_TX_QUEUE_VACANCY, NORM_TX_QUEUE_EMPTY, NORM_TX_FLUSH_COMPLETED, NORM_TX_WATERMARK_COMPLETED, NORM_TX_OBJECT_SENT, NORM_TX_OBJECT_PURGED, NORM_LOCAL_SENDER_CLOSED, NORM_REMOTE_SENDER_NEW, NORM_REMOTE_SENDER_ACTIVE, NORM_REMOTE_SENDER_INACTIVE, NORM_REMOTE_SENDER_PURGED, NORM_RX_OBJECT_NEW, NORM_RX_OBJECT_INFO, NORM_RX_OBJECT_UPDATED, NORM_RX_OBJECT_COMPLETED, NORM_RX_OBJECT_ABORTED, NORM_GRTT_UPDATED, NORM_CC_ACTIVE, NORM_CC_INACTIVE }; typedef struct { NormEventType type; NormSessionHandle session; NormNodeHandle sender; NormObjectHandle object; } NormEvent; /** NORM API General Initialization and Operation Functions */ NORM_API_LINKAGE NormInstanceHandle NormCreateInstance(bool priorityBoost = false); NORM_API_LINKAGE void NormDestroyInstance(NormInstanceHandle instanceHandle); NORM_API_LINKAGE void NormStopInstance(NormInstanceHandle instanceHandle); NORM_API_LINKAGE bool NormRestartInstance(NormInstanceHandle instanceHandle); // This MUST be set to enable NORM_OBJECT_FILE reception! // (otherwise received files are ignored) NORM_API_LINKAGE bool NormSetCacheDirectory(NormInstanceHandle instanceHandle, const char* cachePath); // This call blocks until the next NormEvent is ready unless asynchronous // notification is used (see below) NORM_API_LINKAGE bool NormGetNextEvent(NormInstanceHandle instanceHandle, NormEvent* theEvent); // The "NormGetDescriptor()" function returns a HANDLE (WIN32) or // a file descriptor (UNIX) which can be used for async notification // of pending NORM events. On WIN32, the returned HANDLE can be used // with system calls like "WaitForSingleEvent()", and on Unix the // returned descriptor can be used in a "select()" call. If this type // of asynchronous notification is used, calls to "NormGetNextEvent()" will // not block when the notification is posted. #ifdef WIN32 typedef HANDLE NormDescriptor; #else typedef int NormDescriptor; #endif // if/else WIN32/UNIX extern NORM_API_LINKAGE const NormDescriptor NORM_DESCRIPTOR_INVALID; NORM_API_LINKAGE NormDescriptor NormGetDescriptor(NormInstanceHandle instanceHandle); /** NORM Session Creation and Control Functions */ NORM_API_LINKAGE NormSessionHandle NormCreateSession(NormInstanceHandle instanceHandle, const char* sessionAddress, unsigned short sessionPort, NormNodeId localNodeId); NORM_API_LINKAGE void NormDestroySession(NormSessionHandle sessionHandle); NORM_API_LINKAGE void NormSetUserData(NormSessionHandle sessionHandle, const void* userData); NORM_API_LINKAGE const void* NormGetUserData(NormSessionHandle sessionHandle); NORM_API_LINKAGE NormNodeId NormGetLocalNodeId(NormSessionHandle sessionHandle); NORM_API_LINKAGE void NormSetTxPort(NormSessionHandle sessionHandle, unsigned short txPortNumber); NORM_API_LINKAGE void NormSetRxPortReuse(NormSessionHandle sessionHandle, bool enable, bool bindToSessionAddress = true); NORM_API_LINKAGE bool NormSetMulticastInterface(NormSessionHandle sessionHandle, const char* interfaceName); NORM_API_LINKAGE bool NormSetTTL(NormSessionHandle sessionHandle, unsigned char ttl); NORM_API_LINKAGE bool NormSetTOS(NormSessionHandle sessionHandle, unsigned char tos); NORM_API_LINKAGE bool NormSetLoopback(NormSessionHandle sessionHandle, bool loopback); // Special functions for debug support NORM_API_LINKAGE void NormSetMessageTrace(NormSessionHandle sessionHandle, bool state); NORM_API_LINKAGE void NormSetTxLoss(NormSessionHandle sessionHandle, double percent); NORM_API_LINKAGE void NormSetRxLoss(NormSessionHandle sessionHandle, double percent); /** NORM Sender Functions */ NORM_API_LINKAGE bool NormStartSender(NormSessionHandle sessionHandle, NormSessionId sessionId, unsigned long bufferSpace, unsigned short segmentSize, unsigned char numData, unsigned char numParity); NORM_API_LINKAGE void NormStopSender(NormSessionHandle sessionHandle); NORM_API_LINKAGE double NormGetTransmitRate(NormSessionHandle sessionHandle); NORM_API_LINKAGE void NormSetTransmitRate(NormSessionHandle sessionHandle, double bitsPerSecond); NORM_API_LINKAGE bool NormSetTxSocketBuffer(NormSessionHandle sessionHandle, unsigned int bufferSize); NORM_API_LINKAGE void NormSetCongestionControl(NormSessionHandle sessionHandle, bool state); NORM_API_LINKAGE void NormSetTransmitRateBounds(NormSessionHandle sessionHandle, double rateMin, double rateMax); NORM_API_LINKAGE void NormSetTransmitCacheBounds(NormSessionHandle sessionHandle, NormSize sizeMax, unsigned long countMin, unsigned long countMax); NORM_API_LINKAGE void NormSetAutoParity(NormSessionHandle sessionHandle, unsigned char autoParity); NORM_API_LINKAGE void NormSetGrttEstimate(NormSessionHandle sessionHandle, double grttEstimate); NORM_API_LINKAGE double NormGetGrttEstimate(NormSessionHandle sessionHandle); NORM_API_LINKAGE void NormSetGrttMax(NormSessionHandle sessionHandle, double grttMax); NORM_API_LINKAGE void NormSetGrttProbingMode(NormSessionHandle sessionHandle, NormProbingMode probingMode); NORM_API_LINKAGE void NormSetGrttProbingInterval(NormSessionHandle sessionHandle, double intervalMin, double intervalMax); NORM_API_LINKAGE void NormSetBackoffFactor(NormSessionHandle sessionHandle, double backoffFactor); NORM_API_LINKAGE void NormSetGroupSize(NormSessionHandle sessionHandle, unsigned int groupSize); NORM_API_LINKAGE NormObjectHandle NormFileEnqueue(NormSessionHandle sessionHandle, const char* fileName, const char* infoPtr = (const char*)0, unsigned int infoLen = 0); NORM_API_LINKAGE NormObjectHandle NormDataEnqueue(NormSessionHandle sessionHandle, const char* dataPtr, unsigned long dataLen, const char* infoPtr = (const char*)0, unsigned int infoLen = 0); NORM_API_LINKAGE bool NormRequeueObject(NormSessionHandle sessionHandle, NormObjectHandle objectHandle); NORM_API_LINKAGE NormObjectHandle NormStreamOpen(NormSessionHandle sessionHandle, unsigned long bufferSize); NORM_API_LINKAGE void NormStreamClose(NormObjectHandle streamHandle, bool graceful = false); NORM_API_LINKAGE unsigned int NormStreamWrite(NormObjectHandle streamHandle, const char* buffer, unsigned int numBytes); NORM_API_LINKAGE void NormStreamFlush(NormObjectHandle streamHandle, bool eom = false, NormFlushMode flushMode = NORM_FLUSH_PASSIVE); NORM_API_LINKAGE void NormStreamSetAutoFlush(NormObjectHandle streamHandle, NormFlushMode flushMode); NORM_API_LINKAGE void NormStreamSetPushEnable(NormObjectHandle streamHandle, bool pushEnable); NORM_API_LINKAGE bool NormStreamHasVacancy(NormObjectHandle streamHandle); NORM_API_LINKAGE void NormStreamMarkEom(NormObjectHandle streamHandle); NORM_API_LINKAGE bool NormSetWatermark(NormSessionHandle sessionHandle, NormObjectHandle objectHandle); NORM_API_LINKAGE bool NormAddAckingNode(NormSessionHandle sessionHandle, NormNodeId nodeId); NORM_API_LINKAGE void NormRemoveAckingNode(NormSessionHandle sessionHandle, NormNodeId nodeId); NORM_API_LINKAGE NormAckingStatus NormGetAckingStatus(NormSessionHandle sessionHandle, NormNodeId nodeId = NORM_NODE_ANY); /* NORM Receiver Functions */ NORM_API_LINKAGE bool NormStartReceiver(NormSessionHandle sessionHandle, unsigned long bufferSpace); NORM_API_LINKAGE void NormStopReceiver(NormSessionHandle sessionHandle); NORM_API_LINKAGE bool NormSetRxSocketBuffer(NormSessionHandle sessionHandle, unsigned int bufferSize); NORM_API_LINKAGE void NormSetSilentReceiver(NormSessionHandle sessionHandle, bool silent, int maxDelay = -1); NORM_API_LINKAGE void NormSetDefaultUnicastNack(NormSessionHandle sessionHandle, bool unicastNacks); NORM_API_LINKAGE void NormNodeSetUnicastNack(NormNodeHandle remoteSender, bool unicastNacks); NORM_API_LINKAGE void NormSetDefaultNackingMode(NormSessionHandle sessionHandle, NormNackingMode nackingMode); NORM_API_LINKAGE void NormNodeSetNackingMode(NormNodeHandle nodeHandle, NormNackingMode nackingMode); NORM_API_LINKAGE void NormObjectSetNackingMode(NormObjectHandle objectHandle, NormNackingMode nackingMode); NORM_API_LINKAGE void NormSetDefaultRepairBoundary(NormSessionHandle sessionHandle, NormRepairBoundary repairBoundary); NORM_API_LINKAGE void NormNodeSetRepairBoundary(NormNodeHandle nodeHandle, NormRepairBoundary repairBoundary); NORM_API_LINKAGE bool NormStreamRead(NormObjectHandle streamHandle, char* buffer, unsigned int* numBytes); NORM_API_LINKAGE bool NormStreamSeekMsgStart(NormObjectHandle streamHandle); NORM_API_LINKAGE unsigned long NormStreamGetReadOffset(NormObjectHandle streamHandle); /** NORM Object Functions */ NORM_API_LINKAGE NormObjectType NormObjectGetType(NormObjectHandle objectHandle); NORM_API_LINKAGE bool NormObjectHasInfo(NormObjectHandle objectHandle); NORM_API_LINKAGE unsigned short NormObjectGetInfoLength(NormObjectHandle objectHandle); NORM_API_LINKAGE unsigned short NormObjectGetInfo(NormObjectHandle objectHandle, char* buffer, unsigned short bufferLen); NORM_API_LINKAGE NormSize NormObjectGetSize(NormObjectHandle objectHandle); NORM_API_LINKAGE NormSize NormObjectGetBytesPending(NormObjectHandle objectHandle); NORM_API_LINKAGE void NormObjectCancel(NormObjectHandle objectHandle); NORM_API_LINKAGE void NormObjectRetain(NormObjectHandle objectHandle); NORM_API_LINKAGE void NormObjectRelease(NormObjectHandle objectHandle); NORM_API_LINKAGE bool NormFileGetName(NormObjectHandle fileHandle, char* nameBuffer, unsigned int bufferLen); NORM_API_LINKAGE bool NormFileRename(NormObjectHandle fileHandle, const char* fileName); NORM_API_LINKAGE const char*volatile NormDataAccessData(NormObjectHandle objectHandle); NORM_API_LINKAGE char* NormDataDetachData(NormObjectHandle objectHandle); NORM_API_LINKAGE NormNodeHandle NormObjectGetSender(NormObjectHandle objectHandle); NORM_API_LINKAGE char* NormGetData(NormObjectHandle dataHandle); /** NORM Node Functions */ NORM_API_LINKAGE NormNodeId NormNodeGetId(NormNodeHandle nodeHandle); NORM_API_LINKAGE bool NormNodeGetAddress(NormNodeHandle nodeHandle, char* addrBuffer, unsigned int* bufferLen, unsigned short* port = (unsigned short*)0); NORM_API_LINKAGE double NormNodeGetGrtt(NormNodeHandle nodeHandle); // The next 4 functions have not yet been implemented // (work in progress) NORM_API_LINKAGE void NormNodeSetAutoDelete(NormNodeHandle nodeHandle, bool autoDelete); NORM_API_LINKAGE void NormNodeDeleteSender(NormNodeHandle nodeHandle); NORM_API_LINKAGE bool NormNodeAllowSender(NormNodeId senderId); NORM_API_LINKAGE bool NormNodeDenySender(NormNodeId senderId); NORM_API_LINKAGE void NormNodeRetain(NormNodeHandle nodeHandle); NORM_API_LINKAGE void NormNodeRelease(NormNodeHandle nodeHandle); /** Some experimental functions */ NORM_API_LINKAGE unsigned long NormCountCompletedObjects(NormSessionHandle sessionHandle); #endif // _NORM_API