MPR Native API

The Multithreaded Portable Runtime (MPR) is a portable runtime library for embedded applications.

Description:

The MPR provides management for logging, error handling, events, files, http, memory, ssl, sockets, strings, xml parsing, and date/time functions. It also provides a foundation of safe routines for secure programming, that help to prevent buffer overflows and other security threats. The MPR is a library and a C API that can be used in both C and C++ programs.

The MPR uses a set extended typedefs for common types. These include: bool, cchar, cvoid, uchar, short, ushort, int, uint, long, ulong, int32, uint32, int64, uint64, float, and double. The cchar type is a const char, cvoid is const void. Several types have "u" prefixes to denote unsigned qualifiers.

The MPR includes a memory allocator and generational garbage collector. The allocator is a fast, immediate coalescing allocator that will return memory back to the O/S if not required. It is optimized for frequent allocations of small blocks (< 4K) and uses a scheme of free queues for fast allocation.

The MPR provides a high-performance thread-pool to share threads as required to service clients. When a client request arrives, the MPR allocates an event queue called a dispatcher. This dispatcher then serializes all activity for the request so that it essentially runs single-threaded This simplifies the code as most interactions do not need to be lock protected. When a request has activity, it borrows a thread from the thread pool, does its work and then returns the thread to the thread pool. This all happens very quickly, so a small pool of threads are effectivelyshared over many requests. Thread are free to block if required, but typically non-blocking patterns are more economical. If you have non-MPR threads that need to call into the MPR, you must synchronize such calls via mprCreateEvent.

Extensions

Mpr Primary MPR application control structure.
MprBuf Dynamic Buffer Module.
MprCache In-memory caching.
MprCmd Command execution Service.
MprDispatcher Event Dispatcher.
MprEvent Event object.
MprFile File I/O Module.
MprFileSystem File system service.
MprFloat Floating Point Services.
MprHash Hash table entry structure.
MprJson JSON Object.
MprList List data structure.
MprLog Logging Services.
MprMem Memory Allocation Service.
MprMime Mime Type hash table entry (the URL extension is the key).
MprModule Loadable Module Service.
MprModuleSerivce Loadable module service.
MprPath Path (filename) Information.
MprSignal Signal control structure.
MprSocket Socket Service.
MprSsl SSL control structure.
MprString Safe String Module.
MprSync Multithreaded Synchronization Services.
MprThread Thread Service.
MprTime Date and Time Service.
MprWaitHandler Wait Handler Service.
MprWorker Worker thread structure.
MprXml Per XML session structure.

Functions

PUBLIC voidassert(bool cond)
 Assert that a condition is true.
PUBLIC char*fmt(char *buf, ssize maxSize, cchar *fmt, ...)
 Format a string into a static buffer.
PUBLIC char*fmtv(char *buf, ssize maxSize, cchar *fmt, va_list args)
 Format a string into a statically allocated buffer.
PUBLIC char*itos(int64 value)
 Convert an integer to a string.
PUBLIC char*itosbuf(char *buf, ssize size, int64 value, int radix)
 Convert an integer to a string buffer.
PUBLIC char*itosradix(int64 value, int radix)
 Convert an integer to a string.
PUBLIC MprSocket*mprAcceptSocket(MprSocket *listen)
 Accept an incoming connection.
PUBLIC MprKey*mprAddDuplicateKey(MprHash *table, cvoid *key, cvoid *ptr)
 Add a duplicate symbol value into the hash table.
PUBLIC voidmprAddFileSystem(MprFileSystem *fs)
 Create and initialize the disk FileSystem.
PUBLIC intmprAddItem(MprList *list, cvoid *item)
 Add an item to a list.
PUBLIC MprKey*mprAddKey(MprHash *table, cvoid *key, cvoid *ptr)
 Add a symbol value into the hash table.
PUBLIC MprKey*mprAddKeyFmt(MprHash *table, cvoid *key, cchar *fmt, ...)
 Add a key with a formatting value into the hash table.
PUBLIC MprKey*mprAddKeyWithType(MprHash *table, cvoid *key, cvoid *ptr, int type)
 Add a symbol value into the hash table and set the key type.
PUBLIC MprMime*mprAddMime(MprHash *table, cchar *ext, cchar *mimeType)
 Add a mime type to the mime type table.
PUBLIC intmprAddNullItem(MprList *list)
 Add a null item to the list.
PUBLIC voidmprAddNullToBuf(MprBuf *buf)
 Add a null character to the buffer contents.
PUBLIC voidmprAddRoot(cvoid *ptr)
 Add a memory block as a root for garbage collection.
PUBLIC MprSignal*mprAddSignalHandler(int signo, void *handler, void *arg, MprDispatcher *dispatcher, int flags)
 Add a signal handler.
PUBLIC MprWaitHandler*mprAddSocketHandler(MprSocket *sp, int mask, MprDispatcher *dispatcher, void *proc, void *data, int flags)
 Add a wait handler to a socket.
PUBLIC voidmprAddSslCiphers(struct MprSsl *ssl, cchar *ciphers)
 Add the ciphers to use for SSL.
PUBLIC voidmprAddStandardSignals(void)
 Add standard trapping of system signals.
PUBLIC voidmprAddTerminator(MprTerminator terminator)
 Add a service terminator.
PUBLIC voidmprAdjustBufEnd(MprBuf *buf, ssize count)
 Adjust the buffer end position.
PUBLIC voidmprAdjustBufStart(MprBuf *buf, ssize count)
 Adjust the buffer start position.
PUBLIC void*mprAlloc(size_t size)
 Allocate a block of memory.
PUBLIC void*mprAllocMem(size_t size, int flags)
 Allocate a block of memory.
PUBLIC void*mprAllocObj(Type type, MprManager manager)
 Allocate an object of a given type.
PUBLIC void*mprAllocObjWithFlags(Type type, MprManager manager, int flags)
 Allocate an object of a given type.
PUBLIC void*mprAllocZeroed(size_t size)
 Allocate a zeroed block of memory.
PUBLIC MprList*mprAppendList(MprList *list, MprList *add)
 Append a list.
PUBLIC boolmprAreCmdEventsEnabled(MprCmd *cmd, int channel)
 Return true if command events are enabled.
PUBLIC voidmprAssert(cchar *loc, cchar *msg)
 Output an assure assertion failed message.
PUBLIC voidmprAtomicAdd(volatile int *target, int value)
 Atomic Add.
PUBLIC voidmprAtomicAdd64(volatile int64 *target, int64 value)
 Atomic 64 bit Add.
PUBLIC voidmprAtomicBarrier(void)
 Apply a full (read+write) memory barrier.
PUBLIC intmprAtomicCas(void *volatile *target, void *expected, cvoid *value)
 Atomic Compare and Swap.
PUBLIC voidmprAtomicListInsert(void **head, void **link, void *item)
 Atomic list insertion.
PUBLIC voidmprAtomicOpen(void)
 Open and initialize the atomic subystem.
PUBLIC MprFile*mprAttachFileFd(int fd, cchar *name, int omode)
 Attach to an existing file descriptor.
PUBLIC intmprAvailableWorkers(void)
 Get the count of available worker threads Return the count of free threads in the worker thread pool.
PUBLIC intmprBackupLog(cchar *path, int count)
 Backup a log.
PUBLIC MprHash*mprBlendHash(MprHash *target, MprHash *other)
 Blend two hash tables.
PUBLIC intmprBlendJson(MprJson *dest, MprJson *src, int flags)
 Blend two JSON objects.
PUBLIC voidmprBreakpoint(void)
 Trigger a breakpoint.
PUBLIC char*mprBufToString(MprBuf *buf)
 Convert the buffer contents to a string.
PUBLIC boolmprCancelShutdown(void)
 Cancel a shutdown request.
PUBLIC boolmprCheckPassword(cchar *plainTextPassword, cchar *passwordHash)
 Check a plain-text password against the defined hashed password.
PUBLIC voidmprClearList(MprList *list)
 Clears the list of all items.
PUBLIC voidmprClearWaiting(void)
 Clear the event service waiting flag.
PUBLIC MprBuf*mprCloneBuf(MprBuf *orig)
 Clone a buffer.
PUBLIC char*mprCloneBufAsString(MprBuf *bp)
 Clone a buffer contents.
PUBLIC char*mprCloneBufMem(MprBuf *bp)
 Clone a buffer contents.
PUBLIC MprHash*mprCloneHash(MprHash *table)
 Copy a hash table.
PUBLIC MprJson*mprCloneJson(MprJson *obj)
 Clone a JSON object.
PUBLIC MprList*mprCloneList(MprList *src)
 Clone a list and all elements.
PUBLIC MprSocket*mprCloneSocket(MprSocket *sp)
 Clone a socket object.
PUBLIC struct,MprSsl*mprCloneSsl(MprSsl *src)
 Create the a new SSL control structure based on an existing structure.
PUBLIC voidmprCloseCmdFd(MprCmd *cmd, int channel)
 Close the command channel.
PUBLIC intmprCloseFile(MprFile *file)
 Close a file.
PUBLIC voidmprCloseSocket(MprSocket *sp, bool graceful)
 Close a socket.
PUBLIC voidmprCompactBuf(MprBuf *buf)
 Compact the buffer contents.
PUBLIC intmprCompareTime(MprTime t1, MprTime t2)
 Compare two times.
PUBLIC intmprConnectSocket(MprSocket *sp, cchar *ip, int port, int flags)
 Connect a client socket.
PUBLIC intmprCopyListContents(MprList *dest, MprList *src)
 Copy list contents.
PUBLIC intmprCopyPath(cchar *from, cchar *to, int omode)
 Copy a file.
PUBLIC Mpr*mprCreate(int argc, char **argv, int flags)
 Initialize the application by creating an instance of the MPR.
PUBLIC MprBuf*mprCreateBuf(ssize initialSize, ssize maxSize)
 Create a new buffer.
PUBLIC MprCache*mprCreateCache(int options)
 Create a new cache object.
PUBLIC intmprCreateCacheService(void)
 Initialize the cache service on startup.
PUBLIC MprCmd*mprCreateCmd(MprDispatcher *dispatcher)
 Create a new Command object.
PUBLIC MprCond*mprCreateCond(void)
 Create a condition lock variable.
PUBLIC MprDiskFileSystem*mprCreateDiskFileSystem(cchar *path)
 Create and initialize the disk FileSystem.
PUBLIC MprDispatcher*mprCreateDispatcher(cchar *name, int flags)
 Create a new event dispatcher.
PUBLIC MprEvent*mprCreateEvent(MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)
 Queue an new event on a dispatcher.
PUBLIC MprHash*mprCreateHash(int hashSize, int flags)
 Create a hash table.
PUBLIC MprHash*mprCreateHashFromWords(cchar *str)
 Create a hash of words.
PUBLIC MprJson*mprCreateJson(int type)
 Create a JSON object.
PUBLIC MprJson*mprCreateJsonValue(cchar *value, int type)
 Create a JSON object value.
PUBLIC MprKeyValue*mprCreateKeyPair(cchar *key, cchar *value, int flags)
 Create a key / value pair.
PUBLIC MprList*mprCreateList(int size, int flags)
 Create a list.
PUBLIC MprList*mprCreateListFromWords(cchar *str)
 Create a list of words.
PUBLIC MprMutex*mprCreateLock(void)
 Create a Mutex lock object.
PUBLIC voidmprCreateLogService(void)
 Initialize the log service.
PUBLIC struct,Mpr*mprCreateMemService(MprManager manager, int flags)
 Create and initialize the Memory service.
PUBLIC MprHash*mprCreateMimeTypes(cchar *path)
 Create the mime types.
PUBLIC MprModule*mprCreateModule(cchar *name, cchar *path, cchar *entry, void *data)
 Create a module.
PUBLIC MprModuleService*mprCreateModuleService(void)
 Create and initialize the module service.
PUBLIC intmprCreateNotifierService(MprWaitService *ws)
 Internal.
PUBLIC intmprCreateOsService(void)
 Create and initialze the O/S dependent subsystem.
PUBLIC MprRomFileSystem*mprCreateRomFileSystem(cchar *path, MprRomInode *inodes)
 Create and initialize the ROM FileSystem.
PUBLIC MprSocket*mprCreateSocket(void)
 Create a socket.
PUBLIC MprSpin*mprCreateSpinLock(void)
 Create a spin lock lock object.
PUBLIC struct,MprSsl*mprCreateSsl(int server)
 Create the SSL control structure.
PUBLIC MprThread*mprCreateThread(cchar *name, void *proc, void *data, ssize stackSize)
 Create a new thread.
PUBLIC intmprCreateTimeService(void)
 Mpr time structure.
PUBLIC MprEvent*mprCreateTimerEvent(MprDispatcher *dispatcher, cchar *name, MprTicks period, void *proc, void *data, int flags)
 Create a timer event.
PUBLIC MprWaitHandler*mprCreateWaitHandler(int fd, int mask, MprDispatcher *dispatcher, void *proc, void *data, int flags)
 Create a wait handler.
PUBLIC char*mprCryptPassword(cchar *password, cchar *salt, int rounds)
 Encrypt a password using the Blowfish algorithm.
PUBLIC intmprDaemon(void)
 Convert the process into a daemon on unix systems.
PUBLIC voidmprDebug(cchar *tags, int level, cchar *fmt, ...)
 Write a log message to the log file when the product is built in debug mode.
PUBLIC char*mprDecode64(cchar *str)
 Decode a null terminated string using base-46 encoding.
PUBLIC char*mprDecode64Block(cchar *buf, ssize *len, int flags)
 Decode a null terminated string using base-46 encoding.
PUBLIC voidmprDecodeLocalTime(struct tm *timep, MprTime time)
 Decode a time value into a tokenized local time value.
PUBLIC voidmprDecodeUniversalTime(struct tm *timep, MprTime time)
 Decode a time value into a tokenized UTC time structure.
PUBLIC voidmprDedicateWorker(MprWorker *worker)
 Dedicate a worker thread to a current real thread.
PUBLIC voidmprDefaultLogHandler(cchar *tags, int level, cchar *msg)
 Default MPR log handler.
PUBLIC intmprDeletePath(cchar *path)
 Delete a file.
PUBLIC MprHash*mprDeserialize(cchar *str)
 Deserialize a simple JSON string and return a hash of properties.
PUBLIC MprHash*mprDeserializeInto(cchar *str, MprHash *hash)
 Deserialize a simple JSON string into the given hash object.
PUBLIC boolmprDestroy(void)
 Destroy the MPR and all services using the MPR.
PUBLIC void*mprDestroyCache(MprCache *cache)
 Destroy a new cache object.
PUBLIC voidmprDestroyCmd(MprCmd *cmd)
 Destroy the command.
PUBLIC voidmprDestroyDispatcher(MprDispatcher *dispatcher)
 Disable a dispatcher from service events.
PUBLIC voidmprDestroyWaitHandler(MprWaitHandler *wp)
 Destroy a wait handler.
PUBLIC voidmprDisableCmdEvents(MprCmd *cmd, int channel)
 Disable command I/O events.
PUBLIC voidmprDisableFileBuffering(MprFile *file)
 Disable file buffering.
PUBLIC voidmprDisconnectCmd(MprCmd *cmd)
 Disconnect a command its underlying I/O channels.
PUBLIC voidmprDisconnectSocket(MprSocket *sp)
 Disconnect a socket by closing its underlying file descriptor.
PUBLIC char*mprEmptyString(void)
 Reference to a permanent preallocated empty string.
PUBLIC voidmprEnableCmdEvents(MprCmd *cmd, int channel)
 Enable command I/O events.
PUBLIC voidmprEnableCmdOutputEvents(MprCmd *cmd, bool on)
 Enable command I/O events for the command's STDOUT and STDERR channels.
PUBLIC voidmprEnableContinuousEvent(MprEvent *event, int enable)
 Enable or disable an event being continous.
PUBLIC intmprEnableFileBuffering(MprFile *file, ssize size, ssize maxSize)
 Enable file buffering.
PUBLIC boolmprEnableGC(bool on)
 Enable or disable the garbage collector.
PUBLIC voidmprEnableSocketEvents(MprSocket *sp, int mask)
 Enable socket events for a socket callback.
PUBLIC char*mprEncode64(cchar *str)
 Encode a string using base-46 encoding.
PUBLIC char*mprEncode64Block(cchar *buf, ssize len)
 Encode buffer using base-46 encoding.
PUBLIC ssizemprEprintf(cchar *fmt, ...)
 Print a formatted message to the standard error channel.
PUBLIC voidmprError(cchar *fmt, ...)
 Log an error message.
PUBLIC char*mprEscapeCmd(cchar *cmd, int escChar)
 Encode a string escaping typical command (shell) characters.
PUBLIC char*mprEscapeHtml(cchar *html)
 Encode a string by escaping typical HTML characters.
PUBLIC char*mprEscapeSQL(cchar *cmd)
 Encode a string by escaping SQL special characters.
PUBLIC intmprExpireCacheItem(MprCache *cache, cchar *key, MprTicks expires)
 Set the expiry date for a cache item.
PUBLIC voidmprFinalizeCmd(MprCmd *cmd)
 Finalize the writing of data to the command process.
PUBLIC voidmprFlushBuf(MprBuf *buf)
 Flush the buffer contents.
PUBLIC intmprFlushFile(MprFile *file)
 Flush any buffered write data.
PUBLIC ssizemprFlushSocket(MprSocket *sp)
 Flush a socket.
PUBLIC voidmprFormatJsonName(MprBuf *buf, cchar *name, int flags)
 Format a JSON name into and output buffer.
PUBLIC voidmprFormatJsonString(MprBuf *buf, cchar *value)
 Format a string as a JSON string.
PUBLIC voidmprFormatJsonValue(MprBuf *buf, int type, cchar *value, int flags)
 Format a value as a simple JSON string.
PUBLIC char*mprFormatLocalTime(cchar *fmt, MprTime time)
 Convert a time value to local time and format as a string.
PUBLIC char*mprFormatTm(cchar *fmt, struct tm *timep)
 Format a time value as a local time.
PUBLIC char*mprFormatUniversalTime(cchar *fmt, MprTime time)
 Convert a time value to universal time and format as a string.
PUBLIC ssizemprFprintf(struct MprFile *file, cchar *fmt, ...)
 Print a formatted message to a file descriptor.
PUBLIC intmprGC(int flags)
 Collect garbage.
PUBLIC char*mprGetAbsPath(cchar *path)
 Convert a path to an absolute path.
PUBLIC ssizemprGetActiveCmdCount(void)
 Get the count of active commands.
PUBLIC cchar*mprGetAppDir(void)
 Get the application directory.
PUBLIC cchar*mprGetAppName(void)
 Get the application name defined via mprSetAppName.
PUBLIC cchar*mprGetAppPath(void)
 Get the application executable path.
PUBLIC cchar*mprGetAppTitle(void)
 Get the application title string.
PUBLIC cchar*mprGetAppVersion(void)
 Get the application version string.
PUBLIC ssizemprGetBlockFromBuf(MprBuf *buf, char *blk, ssize count)
 Get a block of data from the buffer.
PUBLIC size_tmprGetBlockSize(cvoid *ptr)
 Get the allocated size of a memory block.
PUBLIC char*mprGetBuf(MprBuf *buf)
 Get the origin of the buffer content storage.
PUBLIC char*mprGetBufEnd(MprBuf *buf)
 Get a reference to the end of the buffer contents.
PUBLIC ssizemprGetBufLength(MprBuf *buf)
 Get the buffer content length.
PUBLIC MprBufProcmprGetBufRefillProc(MprBuf *buf)
 Get the buffer refill procedure.
PUBLIC ssizemprGetBufSize(MprBuf *buf)
 Get the current size of the buffer content storage.
PUBLIC ssizemprGetBufSpace(MprBuf *buf)
 Get the space available to store content.
PUBLIC char*mprGetBufStart(MprBuf *buf)
 Get the start of the buffer contents.
PUBLIC ssizemprGetBusyWorkerCount(void)
 Get the count of workers in the busy queue.
PUBLIC uint64mprGetCPU(void)
 Return the process CPU usage.
PUBLIC voidmprGetCacheStats(MprCache *cache, int *numKeys, ssize *mem)
 Get the Cache statistics.
PUBLIC intmprGetCharFromBuf(MprBuf *buf)
 Get a character from the buffer.
PUBLIC MprBuf*mprGetCmdBuf(MprCmd *cmd, int channel)
 Get the underlying buffer for a channel.
PUBLIC intmprGetCmdExitStatus(MprCmd *cmd)
 Get the command exit status.
PUBLIC intmprGetCmdFd(MprCmd *cmd, int channel)
 Get the underlying file descriptor for an I/O channel.
PUBLIC boolmprGetCmdlineLogging(void)
 Get if command line logging is being used.
PUBLIC MprOsThreadmprGetCurrentOsThread(void)
 Get the O/S thread.
PUBLIC cchar*mprGetCurrentPath(void)
 Return the current working directory.
PUBLIC MprThread*mprGetCurrentThread(void)
 Get the currently executing thread.
PUBLIC cchar*mprGetCurrentThreadName(void)
 Return the name of the current thread.
PUBLIC MprWorker*mprGetCurrentWorker(void)
 Get the worker object if the current thread is actually a worker thread.
PUBLIC char*mprGetDate(char *fmt)
 Get a string representation of the current date/time.
PUBLIC boolmprGetDebugMode(void)
 Get the debug mode.
PUBLIC MprDispatcher*mprGetDispatcher(void)
 Get the MPR primary dispatcher.
PUBLIC cchar*mprGetDomainName(void)
 Get the application domain name string.
PUBLIC MprTicksmprGetElapsedTicks(MprTicks mark)
 Get the elapsed time since a ticks mark.
PUBLIC MprTimemprGetElapsedTime(MprTime mark)
 Get the elapsed time since a starting time mark.
PUBLIC intmprGetEndian(void)
 Return the endian byte ordering for the application.
PUBLIC intmprGetError(void)
 Return the error code for the most recent system or library operation.
PUBLIC int64mprGetEventMark(MprDispatcher *dispatcher)
 Get an event mark for a dispatcher.
PUBLIC intmprGetExitStatus(void)
 Get the exit status.
PUBLIC intmprGetFileChar(MprFile *file)
 Read a character from the file.
PUBLIC intmprGetFileFd(MprFile *file)
 Get the file descriptor for a file.
PUBLIC MprOffmprGetFilePosition(MprFile *file)
 Return the current file position.
PUBLIC MprOffmprGetFileSize(MprFile *file)
 Get the size of the file.
PUBLIC void*mprGetFirstItem(MprList *list)
 Get the first item in the list.
PUBLIC MprKey*mprGetFirstKey(MprHash *table)
 Return the first symbol in a symbol entry.
PUBLIC cchar*mprGetFirstPathSeparator(cchar *path)
 Get the first path separator in a path.
PUBLIC intmprGetHashLength(MprHash *table)
 Return the count of symbols in a symbol entry.
PUBLIC uint64mprGetHiResTicks(void)
 Get the CPU tick count.
PUBLIC cchar*mprGetHostName(void)
 Get the application host name string.
PUBLIC cchar*mprGetIpAddr(void)
 Get the application IP address string.
PUBLIC void*mprGetItem(MprList *list, int index)
 Get an list item.
PUBLIC cchar*mprGetJson(MprJson *obj, cchar *key)
 Get a JSON key and return a string value.
PUBLIC ssizemprGetJsonLength(MprJson *obj)
 Get the number of child properties in a JSON object.
PUBLIC MprJson*mprGetJsonObj(MprJson *obj, cchar *key)
 Get a parsed JSON object for a key value.
PUBLIC void*mprGetKey(cchar *key)
 Get a key value.
PUBLIC void*mprGetLastItem(MprList *list)
 Get the last item in the list.
PUBLIC intmprGetListCapacity(MprList *list)
 Get the current capacity of the list.
PUBLIC intmprGetListLength(MprList *list)
 Get the number of items in the list.
PUBLIC struct,MprFile*mprGetLogFile(void)
 Get the log file object.
PUBLIC MprLogHandlermprGetLogHandler(void)
 Get the current MPR debug log handler.
PUBLIC intmprGetLogLevel(void)
 Get the current logging level.
PUBLIC char*mprGetMD5(cchar *str)
 Get an MD5 checksum.
PUBLIC char*mprGetMD5WithPrefix(cchar *buf, ssize len, cchar *prefix)
 Get an MD5 checksum with optional prefix string and buffer length.
PUBLIC intmprGetMaxWorkers(void)
 Get the maximum count of worker pool threads Get the maximum limit of worker pool threads.
PUBLIC size_tmprGetMem(void)
 Return the amount of memory currently used by the application.
PUBLIC MprMemStats*mprGetMemStats(void)
 Return the current allocation memory statistics block.
PUBLIC cchar*mprGetMimeProgram(MprHash *table, cchar *mimeType)
 Get the mime type program for a given mimeType.
PUBLIC cchar*mprGetModuleSearchPath(void)
 Get the module search path.
PUBLIC Mpr*mprGetMpr(void)
 Return the MPR control instance.
PUBLIC char*mprGetNativePath(cchar *path)
 Get a path formatted according to the native O/S conventions.
PUBLIC void*mprGetNextItem(MprList *list, int *lastIndex)
 Get the next item in the list.
PUBLIC MprKey*mprGetNextKey(MprHash *table, MprKey *last)
 Return the next symbol in a symbol entry.
PUBLIC void*mprGetNextStableItem(MprList *list, int *lastIndex)
 Get the next item in a stable list.
PUBLIC intmprGetOsError(void)
 Return the O/S error code.
PUBLIC intmprGetPageSize(void)
 Get the current O/S virtual page size.
PUBLIC char*mprGetPassword(cchar *prompt)
 Get a password from the terminal console.
PUBLIC char*mprGetPathBase(cchar *path)
 Get the base portion of a path.
PUBLIC cchar*mprGetPathBaseRef(cchar *path)
 Get a reference to the base portion of a path.
PUBLIC char*mprGetPathDir(cchar *path)
 Get the directory portion of a path.
PUBLIC char*mprGetPathExt(cchar *path)
 Get the file extension portion of a path.
PUBLIC MprList*mprGetPathFiles(cchar *dir, int flags)
 Create a list of files in a directory or subdirectories.
PUBLIC char*mprGetPathFirstDir(cchar *path)
 Get the first directory portion of a path.
PUBLIC intmprGetPathInfo(cchar *path, MprPath *info)
 Return information about a file represented by a path.
PUBLIC char*mprGetPathLink(cchar *path)
 Get the target of a symbolic link.
PUBLIC cchar*mprGetPathNewline(cchar *path)
 Get the file newline character string for a given path.
PUBLIC char*mprGetPathParent(cchar *path)
 Get the parent directory of a path.
PUBLIC charmprGetPathSeparator(cchar *path)
 Get the default path directory separator.
PUBLIC cchar*mprGetPathSeparators(cchar *path)
 Get the path directory separator.
PUBLIC char*mprGetPortablePath(cchar *path)
 Get a portable path.
PUBLIC void*mprGetPrevItem(MprList *list, int *lastIndex)
 Get the previous item in the list.
PUBLIC intmprGetRandomBytes(char *buf, ssize size, bool block)
 Get some random data.
PUBLIC char*mprGetRandomString(ssize size)
 Get some random data in ascii.
PUBLIC char*mprGetRelPath(cchar *dest, cchar *origin)
 Get a path relative to another path.
PUBLIC MprTicksmprGetRemainingTicks(MprTicks mark, MprTicks timeout)
 Return the time remaining until a timeout has elapsed.
PUBLIC MprRomInode*mprGetRomFiles(void)
 Get the ROM file system data.
PUBLIC char*mprGetSHA(cchar *str)
 Get an SHA1 checksum.
PUBLIC char*mprGetSHABase64(cchar *str)
 Get an SHA1 checksum of a null terminated string.
PUBLIC char*mprGetSHAWithPrefix(cchar *buf, ssize len, cchar *prefix)
 Get an SHA1 checksum with optional prefix string and buffer length.
PUBLIC cchar*mprGetServerName(void)
 Get the application server name string.
PUBLIC boolmprGetSocketBlockingMode(MprSocket *sp)
 Get the socket blocking mode.
PUBLIC intmprGetSocketError(MprSocket *sp)
 Get a socket error code.
PUBLIC SocketmprGetSocketHandle(MprSocket *sp)
 Get the socket file descriptor.
PUBLIC intmprGetSocketInfo(cchar *ip, int port, int *family, int *protocol, struct sockaddr **addr, Socklen *addrlen)
 Get the socket for an IP:Port address.
PUBLIC intmprGetSocketPort(MprSocket *sp)
 Get the port used by a socket.
PUBLIC char*mprGetSocketState(MprSocket *sp)
 Get the socket state.
PUBLIC intmprGetState(void)
 Get the MPR execution state.
PUBLIC MprFile*mprGetStderr(void)
 Return a file object for the Stderr I/O channel.
PUBLIC MprFile*mprGetStdin(void)
 Return a file object for the Stdin I/O channel.
PUBLIC MprFile*mprGetStdout(void)
 Return a file object for the Stdout I/O channel.
PUBLIC char*mprGetTempPath(cchar *tmpDir)
 Make a temporary file.
PUBLIC cchar*mprGetThreadName(MprThread *thread)
 Get the thread name.
PUBLIC MprTicksmprGetTicks(void)
 Get the system time.
PUBLIC MprTimemprGetTime(void)
 Get the time.
PUBLIC intmprGetTimeZoneOffset(MprTime when)
 Get the current timezone offset for a given time.
PUBLIC char*mprGetWinPath(cchar *path)
 Convert a path to an absolute windows path.
PUBLIC voidmprGetWorkerStats(MprWorkerStats *stats)
 Get the Worker service statistics.
PUBLIC MprList*mprGlobPathFiles(cchar *path, cchar *patterns, int flags)
 Create a list of files in a directory or subdirectories that match the given wildcard pattern.
PUBLIC voidmprGlobalLock(void)
 Globally lock the application.
PUBLIC voidmprGlobalUnlock(void)
 Unlock the global mutex.
PUBLIC intmprGrowBuf(MprBuf *buf, ssize count)
 Grow the buffer.
PUBLIC boolmprHasDualNetworkStack(void)
 has the system got a dual IPv4 + IPv6 network stack.
PUBLIC boolmprHasIPv6(void)
 Determine if the system support IPv6.
PUBLIC boolmprHasMemError(void)
 Determine if the MPR has encountered memory allocation errors.
PUBLIC boolmprHasSecureSockets(void)
 Determine if SSL is available.
PUBLIC char*mprHashKeysToString(MprHash *hash, cchar *join)
 Convert hash keys to a single string.
PUBLIC MprJson*mprHashToJson(MprHash *hash)
 Convert a hash object into a JSON object.
PUBLIC char*mprHashToString(MprHash *hash, cchar *join)
 Convert a hash of strings to a single string.
PUBLIC voidmprHiddenSocketData(MprSocket *sp, ssize len, int dir)
 Indicate that the application layer has buffered data for the socket.
PUBLIC voidmprHold(cvoid *ptr)
 Hold a memory block.
PUBLIC voidmprHoldBlocks(cvoid *ptr, ...)
 Hold memory blocks.
PUBLIC int64mprIncCache(MprCache *cache, cchar *key, int64 amount)
 Increment a numeric cache item.
PUBLIC voidmprInitFileSystem(MprFileSystem *fs, cchar *path)
 Create and initialize the FileSystem subsystem.
PUBLIC voidmprInitList(MprList *list, int flags)
 Initialize a list structure.
PUBLIC MprMutex*mprInitLock(MprMutex *mutex)
 Initialize a statically allocated Mutex lock object.
PUBLIC MprSpin*mprInitSpinLock(MprSpin *lock)
 Initialize a statically allocated spinlock object.
PUBLIC intmprInsertCharToBuf(MprBuf *buf, int c)
 Insert a character into the buffer.
PUBLIC intmprInsertItemAtPos(MprList *list, int index, cvoid *item)
 Insert an item into a list at a specific position.
PUBLIC boolmprIsAbsPathContained(cchar *path, cchar *dir)
 Fast version of mprIsPathContained that works only for absolute paths.
PUBLIC intmprIsCmdComplete(MprCmd *cmd)
 Test if a command is complete.
PUBLIC boolmprIsCmdRunning(MprCmd *cmd)
 Test if the command is still running.
PUBLIC boolmprIsDestroyed(void)
 Determine if the MPR has finished.
PUBLIC boolmprIsDestroying(void)
 Test if the application is terminating and core services are being destroyed All request should immediately terminate.
PUBLIC boolmprIsIPv6(cchar *ip)
 Determine if the IP address is an IPv6 address.
PUBLIC boolmprIsIdle(bool traceRequests)
 Determine if the App is idle.
PUBLIC intmprIsInfinite(double value)
 Test if a double value is infinte.
PUBLIC intmprIsNan(double value)
 Test if a double value is not-a-number.
PUBLIC boolmprIsPathAbs(cchar *path)
 Determine if a path is absolute.
PUBLIC boolmprIsPathContained(cchar *path, cchar *dir)
 Determine if a directory is the same as or a parent of a path.
PUBLIC boolmprIsPathDir(cchar *path)
 Determine if a path is a directory.
PUBLIC boolmprIsPathRel(cchar *path)
 Determine if a path is relative.
PUBLIC boolmprIsPathSeparator(cchar *path, cchar c)
 Test if a character is a path separarator.
PUBLIC boolmprIsSocketEof(MprSocket *sp)
 Test if the other end of the socket has been closed.
PUBLIC boolmprIsSocketSecure(MprSocket *sp)
 Determine if the socket is secure.
PUBLIC boolmprIsSocketV6(MprSocket *sp)
 Determine if the socket is using IPv6 Currently only works for server side addresses.
PUBLIC boolmprIsStopped(void)
 Test if the application is stopped If this routine returns true, the application shutdown has passed the point of no return.
PUBLIC boolmprIsStopping(void)
 Test if the application is stopping If mprIsStopping is true, the application has commenced a shutdown.
PUBLIC intmprIsValid(cvoid *ptr)
 Test is a pointer is a valid memory context.
PUBLIC intmprIsZero(double value)
 Test if a double value is zero.
PUBLIC char*mprJoinPath(cchar *base, cchar *path)
 Join paths.
PUBLIC char*mprJoinPathExt(cchar *path, cchar *ext)
 Join an extension to a path.
PUBLIC char*mprJoinPaths(cchar *base, ...)
 Join paths.
PUBLIC MprList*mprJsonToEnv(MprJson *json, cchar *prefix, MprList *list)
 Convert a JSON object to a string of environment variables.
PUBLIC MprHash*mprJsonToHash(MprJson *json)
 Convert a JSON object into a Hash object.
PUBLIC char*mprJsonToString(MprJson *obj, int flags)
 Serialize a JSON object into a string.
PUBLIC char*mprListToString(MprList *list, cchar *join)
 Convert a list of strings to a single string.
PUBLIC SocketmprListenOnSocket(MprSocket *sp, cchar *ip, int port, int flags)
 Listen on a server socket for incoming connections.
PUBLIC MprJson*mprLoadJson(cchar *path)
 Load a JSON object from a filename.
PUBLIC intmprLoadModule(MprModule *mp)
 Load a module.
PUBLIC intmprLoadNativeModule(MprModule *mp)
 Load a native module.
PUBLIC intmprLoadSsl(void)
 Load the SSL module.
PUBLIC voidmprLog(cchar *tags, int level, cchar *fmt, ...)
 Write a message to the error log file.
PUBLIC voidmprLogConfig(void)
 Show the product configuration at the start of the log file.
PUBLIC voidmprLogJson(int level, MprJson *obj, cchar *fmt, ...)
 Trace the JSON object to the debug log.
PUBLIC intmprLookAtLastCharInBuf(MprBuf *buf)
 Peek at the last character in the buffer.
PUBLIC intmprLookAtNextCharInBuf(MprBuf *buf)
 Peek at the next character in the buffer.
PUBLIC char*mprLookupCache(MprCache *cache, cchar *key, MprTime *modified, int64 *version)
 Lookup an item in the cache.
PUBLIC MprFileSystem*mprLookupFileSystem(cchar *path)
 Lookup a file system.
PUBLIC intmprLookupItem(MprList *list, cvoid *item)
 Find an item and return its index.
PUBLIC void*mprLookupKey(MprHash *table, cvoid *key)
 Lookup a symbol in the hash table.
PUBLIC MprKey*mprLookupKeyEntry(MprHash *table, cvoid *key)
 Lookup a symbol in the hash table and return the hash entry.
PUBLIC cchar*mprLookupMime(MprHash *table, cchar *ext)
 Get the mime type for an extension.
PUBLIC MprModule*mprLookupModule(cchar *name)
 Lookup a module.
PUBLIC void*mprLookupModuleData(cchar *name)
 Lookup a module and return the module data.
PUBLIC intmprLookupStringItem(MprList *list, cchar *str)
 Find a string item and return its index.
PUBLIC intmprMakeArgv(cchar *command, cchar ***argv, int flags)
 Make a argv style array of command arguments.
PUBLIC intmprMakeDir(cchar *path, int perms, int owner, int group, bool makeMissing)
 Make a directory.
PUBLIC intmprMakeLink(cchar *path, cchar *target, bool hard)
 Make a link.
PUBLIC char*mprMakePassword(cchar *password, int saltLength, int rounds)
 Make a password hash for a plain-text password using the Blowfish algorithm.
PUBLIC char*mprMakeSalt(ssize size)
 Make salt for adding to a password.
PUBLIC voidmprMapSeparators(char *path, int separator)
 Map the separators in a path.
PUBLIC voidmprMark(void *ptr)
 Mark a memory block as in-use.
PUBLIC intmprMemcmp(cvoid *b1, size_t b1Len, cvoid *b2, size_t b2Len)
 Compare two byte strings.
PUBLIC size_tmprMemcpy(void *dest, size_t destMax, cvoid *src, size_t nbytes)
 Safe copy for a block of data.
PUBLIC void*mprMemdup(cvoid *ptr, size_t size)
 Duplicate a block of memory.
PUBLIC voidmprNap(MprTicks msec)
 Nap for a while.
PUBLIC boolmprNeedYield(void)
 Test if a thread should call mprYield.
PUBLIC char*mprNormalizePath(cchar *path)
 Normalize a path.
PUBLIC intmprNotifyOn(MprWaitHandler *wp, int mask)
 Begin I/O notification services on a wait handler.
PUBLIC MprFile*mprOpenFile(cchar *filename, int omode, int perms)
 Open a file.
PUBLIC intmprParseArgs(char *command, char **argv, int maxArgs)
 Make a argv style array of command arguments.
PUBLIC MprJson*mprParseJson(cchar *str)
 Parse a JSON string into an object tree.
PUBLIC MprJson*mprParseJsonEx(cchar *str, MprJsonCallback *callback, void *data, MprJson *obj, cchar **errorMsg)
 Extended JSON parsing from a JSON string into an object tree.
PUBLIC MprJson*mprParseJsonInto(cchar *str, MprJson *obj)
 Parse a JSON string into an existing object.
PUBLIC intmprParseSocketAddress(cchar *address, cchar **ip, int *port, int *secure, int defaultPort)
 Parse an socket address IP address.
PUBLIC boolmprPathExists(cchar *path, int omode)
 Determine if a file exists for a path name and can be accessed.
PUBLIC intmprPeekFileChar(MprFile *file)
 Non-destructively read a character from the file.
PUBLIC void*mprPopItem(MprList *list)
 Pop an item.
PUBLIC voidmprPrintMem(cchar *msg, int flags)
 Print a memory usage report to stdout.
PUBLIC ssizemprPrintf(cchar *fmt, ...)
 Formatted print.
PUBLIC char*mprPrintfCore(char *buf, ssize maxsize, cchar *fmt, va_list args)
 Format a string into a buffer.
PUBLIC voidmprPruneCache(MprCache *cache)
 Prune the cache.
PUBLIC intmprPushItem(MprList *list, cvoid *item)
 Push an item onto the list.
PUBLIC ssizemprPutBlockToBuf(MprBuf *buf, cchar *ptr, ssize size)
 Put a block to the buffer.
PUBLIC intmprPutCharToBuf(MprBuf *buf, int c)
 Put a character to the buffer.
PUBLIC ssizemprPutFileChar(MprFile *file, int c)
 Write a character to the file.
PUBLIC ssizemprPutFileString(MprFile *file, cchar *str)
 Write a string to the file.
PUBLIC ssizemprPutIntToBuf(MprBuf *buf, int64 i)
 Put an integer to the buffer.
PUBLIC ssizemprPutPadToBuf(MprBuf *buf, int c, ssize count)
 Put padding characters to the buffer.
PUBLIC ssizemprPutStringToBuf(MprBuf *buf, cchar *str)
 Put a string to the buffer.
PUBLIC ssizemprPutSubStringToBuf(MprBuf *buf, cchar *str, ssize count)
 Put a substring to the buffer.
PUBLIC ssizemprPutToBuf(MprBuf *buf, cchar *fmt, ...)
 Put a formatted string to the buffer.
PUBLIC MprJson*mprQueryJson(MprJson *obj, cchar *key, cchar *value, int type)
 Query a JSON object for a property key path and execute the given command.
PUBLIC voidmprQueueIOEvent(MprWaitHandler *wp)
 Queue an IO event for dispatch on the wait handler dispatcher.
PUBLIC intmprRandom(void)
 Return a random number.
PUBLIC char*mprReadCache(MprCache *cache, cchar *key, MprTime *modified, int64 *version)
 Read an item from the cache.
PUBLIC ssizemprReadCmd(MprCmd *cmd, int channel, char *buf, ssize bufsize)
 Make the I/O channels to send and receive data to and from the command.
PUBLIC ssizemprReadFile(MprFile *file, void *buf, ssize size)
 Read data from a file.
PUBLIC cchar*mprReadJson(MprJson *obj, cchar *name)
 Read a JSON property.
PUBLIC MprJson*mprReadJsonObj(MprJson *obj, cchar *name)
 Read a JSON object.
PUBLIC MprJson*mprReadJsonValue(MprJson *obj, cchar *value)
 Read a JSON object by value.
PUBLIC char*mprReadLine(MprFile *file, ssize size, ssize *len)
 Read a line from the file.
PUBLIC ssizemprReadSocket(MprSocket *sp, void *buf, ssize size)
 Read from a socket.
PUBLIC void*mprRealloc(void *ptr, size_t size)
 Reallocate a block.
PUBLIC intmprReapCmd(MprCmd *cmd, MprTicks timeout)
 Reap the command.
PUBLIC voidmprRecallWaitHandler(MprWaitHandler *wp)
 Recall a wait handler.
PUBLIC voidmprRecallWaitHandlerByFd(Socket fd)
 Recall a wait handler by fd.
PUBLIC intmprRefillBuf(MprBuf *buf)
 Refill the buffer with data.
PUBLIC voidmprRelease(cvoid *ptr)
 Release a memory block.
PUBLIC voidmprReleaseBlocks(cvoid *ptr, ...)
 Release a memory blocks.
PUBLIC voidmprReleaseWorker(MprWorker *worker)
 Release a worker thread.
PUBLIC boolmprRemoveCache(MprCache *cache, cchar *key)
 Remove items from the cache.
PUBLIC voidmprRemoveEvent(MprEvent *event)
 Remove an event.
PUBLIC intmprRemoveItem(MprList *list, cvoid *item)
 Remove an item from the list.
PUBLIC intmprRemoveItemAtPos(MprList *list, int index)
 Remove an item from the list.
PUBLIC MprJson*mprRemoveJson(MprJson *obj, cchar *key)
 Remove a property from a JSON object.
PUBLIC MprJson*mprRemoveJsonChild(MprJson *obj, MprJson *child)
 Remove a child from a JSON object WARNING: do not call this API when traversing the object in question using ITERATE_JSON.
PUBLIC intmprRemoveKey(MprHash *table, cvoid *key)
 Remove a symbol entry from the hash table.
PUBLIC intmprRemoveLastItem(MprList *list)
 Remove the last item from the list.
PUBLIC intmprRemoveRangeOfItems(MprList *list, int start, int end)
 Remove a range of items from the list.
PUBLIC voidmprRemoveRoot(cvoid *ptr)
 Remove a memory block as a root for garbage collection.
PUBLIC voidmprRemoveSocketHandler(MprSocket *sp)
 Remove a socket wait handler.
PUBLIC intmprRemoveStringItem(MprList *list, cchar *str)
 Remove a string item from the list.
PUBLIC voidmprRemoveWaitHandler(MprWaitHandler *wp)
 Remove a wait handler from the wait service.
PUBLIC char*mprReplacePathExt(cchar *path, cchar *ext)
 Replace an extension to a path.
PUBLIC voidmprRescheduleEvent(MprEvent *event, MprTicks period)
 Reschedule an event.
PUBLIC voidmprResetBufIfEmpty(MprBuf *buf)
 Reset the buffer.
PUBLIC voidmprResetCond(MprCond *cond)
 Reset a condition variable.
PUBLIC voidmprResetMemError(void)
 Reset the memory allocation error flag.
PUBLIC voidmprResetYield(void)
 Reset a sticky yield.
PUBLIC char*mprResolvePath(cchar *base, cchar *path)
 Resolve paths.
PUBLIC voidmprRestart(void)
 Restart the application.
PUBLIC voidmprRestartContinuousEvent(MprEvent *event)
 Restart an event.
PUBLIC intmprRun(MprDispatcher *dispatcher, cchar *command, cchar *input, char **output, char **error, MprTicks timeout)
 Run a simple blocking command using a string command line.
PUBLIC intmprRunCmd(MprCmd *cmd, cchar *command, cchar **envp, cchar *in, char **out, char **err, MprTicks timeout, int flags)
 Run a command using a string command line.
PUBLIC intmprRunCmdV(MprCmd *cmd, int argc, cchar **argv, cchar **envp, cchar *in, char **out, char **err, MprTicks timeout, int flags)
 Run a command using an argv[] array of arguments.
PUBLIC intmprSamePath(cchar *path1, cchar *path2)
 Compare two paths if they are the same.
PUBLIC intmprSamePathCount(cchar *path1, cchar *path2, ssize len)
 Compare two paths if they are the same for a given length.
PUBLIC intmprSaveJson(MprJson *obj, cchar *path, int flags)
 Save a JSON object to a filename.
PUBLIC char*mprSearchForModule(cchar *module)
 Search for a module on the current module path.
PUBLIC char*mprSearchPath(cchar *path, int flags, cchar *search, ...)
 Search for a path.
PUBLIC MprOffmprSeekFile(MprFile *file, int seekType, MprOff distance)
 Seek the I/O pointer to a new location in the file.
PUBLIC char*mprSerialize(MprHash *hash, int flags)
 Serialize a hash of properties as a JSON string.
PUBLIC intmprServiceEvents(MprTicks delay, int flags)
 Service events.
PUBLIC boolmprServicesAreIdle(bool traceRequests)
 Determine if the MPR services.
PUBLIC intmprSetAppName(cchar *name, cchar *title, cchar *version)
 Set the application name, title and version.
PUBLIC voidmprSetAppPath(cchar *path)
 Set the application executable path.
PUBLIC voidmprSetBufMax(MprBuf *buf, ssize maxSize)
 Set the maximum buffer size.
PUBLIC voidmprSetBufRefillProc(MprBuf *buf, MprBufProc fn, void *arg)
 Set the buffer refill procedure.
PUBLIC intmprSetBufSize(MprBuf *buf, ssize size, ssize maxSize)
 Set the buffer size.
PUBLIC voidmprSetCacheLimits(MprCache *cache, int64 keys, MprTicks lifespan, int64 memory, int resolution)
 Set the cache resource limits.
PUBLIC intmprSetCacheLink(MprCache *cache, cchar *key, void *link)
 Set a linked managed memory reference for a cached item.
PUBLIC voidmprSetCacheNotify(MprCache *cache, MprCacheProc notify)
 Set a notification callback to be invoked for events of interest on cached items.
PUBLIC voidmprSetCmdCallback(MprCmd *cmd, MprCmdProc callback, void *data)
 Define a callback to be invoked to receive response data from the command.
PUBLIC voidmprSetCmdDefaultEnv(MprCmd *cmd, cchar **env)
 Set the default environment to use for commands.
PUBLIC voidmprSetCmdDir(MprCmd *cmd, cchar *dir)
 Set the home directory for the command.
PUBLIC voidmprSetCmdEnv(MprCmd *cmd, cchar **env)
 Set the command environment.
PUBLIC voidmprSetCmdSearchPath(MprCmd *cmd, cchar *search)
 Set the default command search path.
PUBLIC boolmprSetCmdlineLogging(bool on)
 Set if command line logging was requested.
PUBLIC voidmprSetDebugMode(bool on)
 Turn on debug mode.
PUBLIC voidmprSetDomainName(cchar *s)
 Set the application domain name string.
PUBLIC voidmprSetEnv(cchar *key, cchar *value)
 Set an environment variable value.
PUBLIC voidmprSetError(int error)
 Set the error code.
PUBLIC voidmprSetEventServiceSleep(MprTicks delay)
 Set the maximum sleep time for the event service.
PUBLIC voidmprSetExitStatus(int status)
 Set the proposed exit status.
PUBLIC voidmprSetExitTimeout(MprTicks timeout)
 Set the exit timeout for a shutdown.
PUBLIC voidmprSetFilesLimit(int limit)
 Set the maximum number of open file/socket descriptors.
PUBLIC voidmprSetHostName(cchar *s)
 Set the application host name string.
PUBLIC MprIdleCallbackmprSetIdleCallback(MprIdleCallback idleCallback)
 Define a new idle callback to be invoked by mprIsIdle()
PUBLIC voidmprSetIpAddr(cchar *ip)
 Sete the application IP address string.
PUBLIC void*mprSetItem(MprList *list, int index, cvoid *item)
 Set a list item.
PUBLIC intmprSetJson(MprJson *obj, cchar *key, cchar *value, int type)
 Update a key/value in the JSON object with a string value.
PUBLIC voidmprSetJsonError(MprJsonParser *jp, cchar *fmt, ...)
 Signal a parse error in the JSON input stream.
PUBLIC intmprSetJsonObj(MprJson *obj, cchar *key, MprJson *value)
 Update a property in a JSON object.
PUBLIC voidmprSetKey(cchar *key, void *value)
 Store a key/value pair.
PUBLIC intmprSetListLimits(MprList *list, int initialSize, int maxSize)
 Define the list size limits.
PUBLIC voidmprSetLogBackup(ssize logSize, int backupCount, int flags)
 Set the log rotation parameters.
PUBLIC voidmprSetLogFile(struct MprFile *file)
 Set a file to be used for logging.
PUBLIC MprLogHandlermprSetLogHandler(MprLogHandler handler)
 Set an MPR debug log handler.
PUBLIC voidmprSetLogLevel(int level)
 Set the current logging verbosity level.
PUBLIC void*mprSetManager(void *ptr, MprManager manager)
 Update the manager for a block of memory.
PUBLIC intmprSetMaxSocketAccept(int max)
 Set the maximum number of accepted client connections that are permissable.
PUBLIC voidmprSetMaxWorkers(int count)
 Set the maximum count of worker threads Set the maximum number of worker pool threads for the MPR.
PUBLIC voidmprSetMemError(void)
 Set an memory allocation error condition on a memory context.
PUBLIC voidmprSetMemLimits(ssize warnHeap, ssize maximum, ssize cache)
 Configure the application memory limits.
PUBLIC voidmprSetMemNotifier(MprMemNotifier cback)
 Define a memory notifier.
PUBLIC voidmprSetMemPolicy(int policy)
 Set the memory allocation policy for when allocations fail.
PUBLIC intmprSetMimeProgram(MprHash *table, cchar *mimeType, cchar *program)
 Set the mime type program.
PUBLIC voidmprSetMinWorkers(int count)
 Set the minimum count of worker threads Set the count of threads the worker pool will have.
PUBLIC voidmprSetModuleFinalizer(MprModule *module, MprModuleProc stop)
 Define a module finalizer that will be called before a module is stopped.
PUBLIC voidmprSetModuleSearchPath(char *searchPath)
 Set the module search path.
PUBLIC voidmprSetModuleTimeout(MprModule *module, MprTicks timeout)
 Set a module timeout.
PUBLIC voidmprSetOsError(int error)
 Set the O/S error code.
PUBLIC voidmprSetPathNewline(cchar *path, cchar *newline)
 Set the file system new line character string.
PUBLIC voidmprSetPathSeparators(cchar *path, cchar *separators)
 Set the file system path separators.
PUBLIC voidmprSetServerName(cchar *s)
 Set the application server name string.
PUBLIC intmprSetSocketBlockingMode(MprSocket *sp, bool on)
 Set the socket blocking mode.
PUBLIC voidmprSetSocketDispatcher(MprSocket *sp, MprDispatcher *dispatcher)
 Set the dispatcher to use for socket events.
PUBLIC voidmprSetSocketEof(MprSocket *sp, bool eof)
 Set an EOF condition on the socket.
PUBLIC intmprSetSocketNoDelay(MprSocket *sp, bool on)
 Set the socket delay mode.
PUBLIC voidmprSetSslAlpn(struct MprSsl *ssl, cchar *protocols)
 Set the ALPN protocols for SSL.
PUBLIC voidmprSetSslCaFile(struct MprSsl *ssl, cchar *caFile)
 Set the client certificate file to use for SSL.
PUBLIC voidmprSetSslCaPath(struct MprSsl *ssl, cchar *caPath)
 Set the path for the client certificate directory.
PUBLIC voidmprSetSslCertFile(struct MprSsl *ssl, cchar *certFile)
 Set certificate to use for SSL.
PUBLIC voidmprSetSslCiphers(MprSsl *ssl, cchar *ciphers)
 Set the ciphers to use.
PUBLIC voidmprSetSslHostname(MprSsl *ssl, cchar *hostname)
 Set the desired hostname for this SSL configuration when using SNI.
PUBLIC voidmprSetSslKeyFile(struct MprSsl *ssl, cchar *keyFile)
 Set the key file to use for SSL.
PUBLIC voidmprSetSslLogLevel(struct MprSsl *ssl, int level)
 Set the SSL log level at which to start tracing SSL events.
PUBLIC voidmprSetSslMatch(struct MprSsl *ssl, MprMatchSsl match)
 Set a match callback to select the appropriate SSL configuration to use in response to a client SNI hello.
PUBLIC voidmprSetSslProtocols(struct MprSsl *ssl, int protocols)
 Set the SSL protocol to use.
PUBLIC voidmprSetSslProvider(MprSocketProvider *provider)
 Set the SSL provider to use.
PUBLIC voidmprSetSslRenegotiate(MprSsl *ssl, bool enable)
 Control SSL session renegotiation.
PUBLIC voidmprSetSslRevoke(struct MprSsl *ssl, cchar *revoke)
 Define a list of certificates to revoke.
PUBLIC voidmprSetSslTicket(MprSsl *ssl, bool enable)
 Enable SSL session tickets.
PUBLIC boolmprSetThreadYield(MprThread *tp, bool on)
 Set whether a thread can yield for GC.
PUBLIC voidmprSetWorkerStackSize(int size)
 Set the default worker stack size.
PUBLIC boolmprShouldAbortRequests(void)
 Test if requests should be aborted.
PUBLIC boolmprShouldDenyNewRequests(void)
 Test if new requests should be denied.
PUBLIC voidmprShutdown(int exitStrategy, int status, MprTicks timeout)
 Initiate shutdown of the MPR and application.
PUBLIC voidmprSignalCond(MprCond *cond)
 Signal a condition lock variable.
PUBLIC voidmprSignalDispatcher(MprDispatcher *dispatcher)
 Signal the dispatcher to wakeup and re-examine its queues.
PUBLIC voidmprSignalMultiCond(MprCond *cond)
 Signal a condition lock variable for use with multiple waiters.
PUBLIC voidmprSleep(MprTicks msec)
 Sleep for a while.
PUBLIC boolmprSocketHandshaking(MprSocket *sp)
 Test if the socket is doing an SSL handshake.
PUBLIC boolmprSocketHasBuffered(MprSocket *sp)
 Test if the socket has buffered data.
PUBLIC boolmprSocketHasBufferedRead(MprSocket *sp)
 Test if the socket has buffered read data.
PUBLIC boolmprSocketHasBufferedWrite(MprSocket *sp)
 Test if the socket has buffered write data.
PUBLIC void*mprSort(void *base, ssize num, ssize width, MprSortProc compare, void *ctx)
 Quicksort.
PUBLIC MprList*mprSortList(MprList *list, MprSortProc compare, void *ctx)
 Sort a list.
PUBLIC intmprSslInit(void *unused, MprModule *module)
 Initialize the SSL provider.
PUBLIC intmprStart(void)
 Start the Mpr services.
PUBLIC intmprStartCmd(MprCmd *cmd, int argc, cchar **argv, cchar **envp, int flags)
 Start the command.
PUBLIC intmprStartDispatcher(MprDispatcher *dispatcher)
 Start a dispatcher by setting it on the run queue.
PUBLIC intmprStartEventsThread(void)
 Start an thread dedicated to servicing events.
PUBLIC intmprStartLogging(cchar *logSpec, int flags)
 Start logging.
PUBLIC intmprStartModule(MprModule *mp)
 Start a module.
PUBLIC intmprStartModuleService(void)
 Start the module service.
PUBLIC intmprStartOsService(void)
 Start the O/S dependent subsystem.
PUBLIC intmprStartOsThread(cchar *name, void *proc, void *data, MprThread *tp)
 Start an O/S thread.
PUBLIC intmprStartThread(MprThread *thread)
 Start a thread.
PUBLIC intmprStartWorker(MprWorkerProc proc, void *data)
 Start a worker thread.
PUBLIC SocketmprStealSocketHandle(MprSocket *sp)
 Steal the socket handle.
PUBLIC intmprStopCmd(MprCmd *cmd, int signal)
 Stop the command.
PUBLIC voidmprStopContinuousEvent(MprEvent *event)
 Stop an event.
PUBLIC intmprStopDispatcher(MprDispatcher *dispatcher)
 Stop a dispatcher by removing it from the run queue.
PUBLIC intmprStopModule(MprModule *mp)
 Stop a module.
PUBLIC voidmprStopModuleService(void)
 Stop the module service.
PUBLIC voidmprStopOsService(void)
 Stop the O/S dependent subsystem.
PUBLIC voidmprSuspendThread(MprTicks timeout)
 Suspend the current thread.
PUBLIC char*mprTransformPath(cchar *path, int flags)
 Transform a path.
PUBLIC char*mprTrimPathComponents(cchar *path, int count)
 Trim path components from a path.
PUBLIC char*mprTrimPathDrive(cchar *path)
 Trim the drive from a path.
PUBLIC char*mprTrimPathExt(cchar *path)
 Trim an extension from a path.
PUBLIC intmprTruncateFile(cchar *path, MprOff size)
 Truncate a file.
PUBLIC boolmprTryLock(MprMutex *lock)
 Attempt to lock access.
PUBLIC boolmprTrySpinLock(MprSpin *lock)
 Attempt to lock access on a spin lock.
PUBLIC intmprUnloadModule(MprModule *mp)
 Unload a module.
PUBLIC intmprUnloadNativeModule(MprModule *mp)
 Unload a native module.
PUBLIC intmprUpgradeSocket(MprSocket *sp, struct MprSsl *ssl, cchar *peerName)
 Upgrade a socket to use SSL/TLS.
PUBLIC char*mprUriDecode(cchar *uri)
 Decode a URI string by de-scaping URI characters.
PUBLIC char*mprUriDecodeInSitu(char *uri)
 Decode a URI string by de-scaping URI characters.
PUBLIC char*mprUriEncode(cchar *uri, int map)
 Encode a string by escaping URI characters.
PUBLIC intmprUsingDefaultLogHandler(void)
 Determine if the app is using the default MPR log handler.
PUBLIC voidmprVerifySslDepth(struct MprSsl *ssl, int depth)
 Control the depth of SSL SSL certificate verification.
PUBLIC voidmprVerifySslIssuer(struct MprSsl *ssl, bool on)
 Control the verification of SSL certificate issuers.
PUBLIC voidmprVerifySslPeer(struct MprSsl *ssl, bool on)
 Require verification of peer certificates.
PUBLIC void*mprVirtAlloc(size_t size, int mode)
 Memory virtual memory into the applications address space.
PUBLIC voidmprVirtFree(void *ptr, size_t size)
 Free (unpin) a mapped section of virtual memory.
PUBLIC intmprWaitForCmd(MprCmd *cmd, MprTicks timeout)
 Wait for the command to complete.
PUBLIC intmprWaitForCond(MprCond *cond, MprTicks timeout)
 Wait for a condition lock variable.
PUBLIC intmprWaitForEvent(MprDispatcher *dispatcher, MprTicks timeout, int64 mark)
 Wait for an event to occur on the given dispatcher.
PUBLIC voidmprWaitForIO(MprWaitService *ws, MprTicks timeout)
 Wait for I/O.
PUBLIC intmprWaitForMultiCond(MprCond *cond, MprTicks timeout)
 Wait for a condition lock variable for use with multiple waiters.
PUBLIC intmprWaitForSingleIO(int fd, int mask, MprTicks timeout)
 Wait for I/O on a file descriptor.
PUBLIC voidmprWaitOn(MprWaitHandler *wp, int desiredMask)
 Subscribe for desired wait events.
PUBLIC voidmprWakeEventService(void)
 Wake the event service.
PUBLIC ssizemprWriteCache(MprCache *cache, cchar *key, cchar *value, MprTime modified, MprTicks lifespan, int64 version, int options)
 Write a cache item.
PUBLIC ssizemprWriteCmd(MprCmd *cmd, int channel, cchar *buf, ssize bufsize)
 Write data to an I/O channel.
PUBLIC ssizemprWriteCmdBlock(MprCmd *cmd, int channel, cchar *buf, ssize bufsize)
 Write data to an I/O channel.
PUBLIC ssizemprWriteFile(MprFile *file, cvoid *buf, ssize count)
 Write data to a file.
PUBLIC ssizemprWriteFileFmt(MprFile *file, cchar *fmt, ...)
 Write formatted data to a file.
PUBLIC ssizemprWriteFileString(MprFile *file, cchar *str)
 Write a string to a file.
PUBLIC intmprWriteJson(MprJson *obj, cchar *key, cchar *value, int type)
 Write a key/value in the JSON object with a string value.
PUBLIC intmprWriteJsonObj(MprJson *obj, cchar *key, MprJson *value)
 Write a property in a JSON object.
PUBLIC ssizemprWritePathContents(cchar *path, cchar *buf, ssize len, int mode)
 Create a file and write contents.
PUBLIC ssizemprWriteSocket(MprSocket *sp, cvoid *buf, ssize len)
 Write to a socket.
PUBLIC ssizemprWriteSocketString(MprSocket *sp, cchar *str)
 Write to a string to a socket.
PUBLIC ssizemprWriteSocketVector(MprSocket *sp, MprIOVec *iovec, int count)
 Write a vector to a socket.
PUBLIC cchar*mprXmlGetErrorMsg(MprXml *xp)
 Get the XML error message if mprXmlParse fails.
PUBLIC intmprXmlGetLineNumber(MprXml *xp)
 Get the source XML line number.
PUBLIC void*mprXmlGetParseArg(MprXml *xp)
 Get the XML callback argument.
PUBLIC MprXml*mprXmlOpen(ssize initialSize, ssize maxSize)
 Open an XML parser instance.
PUBLIC intmprXmlParse(MprXml *xp)
 Run the XML parser.
PUBLIC voidmprXmlSetInputStream(MprXml *xp, MprXmlInputStream fn, void *arg)
 Define the XML parser input stream.
PUBLIC voidmprXmlSetParseArg(MprXml *xp, void *parseArg)
 Set the XML callback argument.
PUBLIC voidmprXmlSetParserHandler(MprXml *xp, MprXmlHandler h)
 Set the XML parser data handle.
PUBLIC voidmprYield(int flags)
 Signify to the garbage collector that the thread is ready for garbage collection.
PUBLIC void*palloc(size_t size)
 Allocate a "permanent" block of memory that is not subject GC.
PUBLIC voidpfree(void *ptr)
 Free a "permanent" block of memory allocated via "palloc".
PUBLIC void*prealloc(void *ptr, size_t size)
 Reallocate a "permanent" block of memory allocated via "palloc".
PUBLIC ssizeprint(cchar *fmt, ...)
 Print to stdout and add a trailing newline.
PUBLIC size_tpsize(void *ptr)
 Return the size of the block.
PUBLIC char*scamel(cchar *str)
 Create a camel case version of the string.
PUBLIC intscaselesscmp(cchar *s1, cchar *s2)
 Compare strings ignoring case.
PUBLIC char*scaselesscontains(cchar *str, cchar *pattern)
 Find a pattern in a string with a caseless comparision.
PUBLIC boolscaselessmatch(cchar *s1, cchar *s2)
 Compare strings ignoring case.
PUBLIC char*schr(cchar *str, int c)
 Find a character in a string.
PUBLIC char*sclone(cchar *str)
 Clone a string.
PUBLIC intscmp(cchar *s1, cchar *s2)
 Compare strings.
PUBLIC char*scontains(cchar *str, cchar *pattern)
 Find a pattern in a string.
PUBLIC ssizescopy(char *dest, ssize destMax, cchar *src)
 Copy a string.
PUBLIC cchar*sends(cchar *str, cchar *suffix)
 Test if the string ends with a given pattern.
PUBLIC voidserase(char *str)
 Erase the contents of a string.
PUBLIC char*sfmt(cchar *fmt, ...)
 Format a string.
PUBLIC char*sfmtv(cchar *fmt, va_list args)
 Format a string.
PUBLIC uintshash(cchar *str, ssize len)
 Compute a hash code for a string.
PUBLIC uintshashlower(cchar *str, ssize len)
 Compute a caseless hash code for a string.
PUBLIC char*sjoin(cchar *str, ...)
 Catenate strings.
PUBLIC cchar*sjoinArgs(int argc, cchar **argv, cchar *sep)
 Join an array of strings.
PUBLIC char*sjoinv(cchar *str, va_list args)
 Catenate strings.
PUBLIC ssizeslen(cchar *str)
 Return the length of a string.
PUBLIC char*slower(cchar *str)
 Convert a string to lower case.
PUBLIC boolsmatch(cchar *s1, cchar *s2)
 Compare strings.
PUBLIC intsncaselesscmp(cchar *s1, cchar *s2, ssize len)
 Compare strings ignoring case.
PUBLIC char*sncaselesscontains(cchar *str, cchar *pattern, ssize limit)
 Find a pattern in a string with a limit and a caseless comparision.
PUBLIC char*snclone(cchar *str, ssize len)
 Clone a substring.
PUBLIC intsncmp(cchar *s1, cchar *s2, ssize len)
 Compare strings.
PUBLIC char*sncontains(cchar *str, cchar *pattern, ssize limit)
 Find a pattern in a string with a limit.
PUBLIC ssizesncopy(char *dest, ssize destMax, cchar *src, ssize len)
 Copy characters from a string.
PUBLIC char*spbrk(cchar *str, cchar *set)
 Locate the a character from a set in a string.
PUBLIC char*sptok(char *str, cchar *pattern, char **last)
 Tokenize a string.
PUBLIC char*srchr(cchar *str, int c)
 Find a character in a string by searching backwards.
PUBLIC char*srejoin(char *buf, ...)
 Append strings to an existing string and reallocate as required.
PUBLIC char*srejoinv(char *buf, va_list args)
 Append strings to an existing string and reallocate as required.
PUBLIC char*ssplit(char *str, cchar *delim, char **last)
 Split a string at a delimiter.
PUBLIC ssizesspn(cchar *str, cchar *set)
 Find the end of a spanning prefix.
PUBLIC boolsstarts(cchar *str, cchar *prefix)
 Test if the string starts with a given pattern.
PUBLIC char*ssub(cchar *str, ssize offset, ssize length)
 Create a substring.
PUBLIC char*stemplate(cchar *str, struct MprHash *tokens)
 Replace template tokens in a string with values from a lookup table.
PUBLIC char*stemplateJson(cchar *str, struct MprJson *tokens)
 Replace template tokens in a string with values from a lookup table.
PUBLIC char*stitle(cchar *str)
 Create a Title Case version of the string.
PUBLIC doublestof(cchar *str)
 Convert a string to a double.
PUBLIC int64stoi(cchar *str)
 Convert a string to an integer.
PUBLIC int64stoiradix(cchar *str, int radix, int *err)
 Convert a string to an integer.
PUBLIC char*stok(char *str, cchar *delim, char **last)
 Tokenize a string.
PUBLIC struct,MprList*stolist(cchar *src)
 String to list.
PUBLIC char*strim(cchar *str, cchar *set, int where)
 Trim a string.
PUBLIC char*supper(cchar *str)
 Convert a string to upper case.

Typedefs

MprBufProcBuffer refill callback function.
MprCacheProcCache item expiry callback.
MprCmdServiceCommand execution service.
MprCondCondition variable for single and multi-thread synchronization.
MprDirEntryDirectory entry description.
MprEventProcEvent callback function.
MprForkCallbackCallback function before doing a fork().
MprFreeMemBlock structure when on a free list.
MprFreeQueueFree queue head structure.
MprHashHash table control structure.
MprHashProcHashing function to use for the table.
MprHeapMemory allocator heap.
MprIOVecVectored write array.
MprJsonCallbackJSON parsing callbacks.
MprJsonParserJSON parser.
MprKeyValueKey value pairs for use with MprList or MprKey.
MprListCompareProcList comparison procedure for sorting.
MprLogHandlerLog handler callback type.
MprManagerMpr memory block manager prototype.
MprMemNotifierMemory allocation error callback.
MprMemStatsMemory allocator statistics.
MprModuleEntryLoadable module entry point signature.
MprModuleProcModule start/stop point function signature.
MprMutexMultithreading lock control structure.
MprOffSigned file offset data type.
MprRegionMemmory regions allocated from the O/S.
MprRomInodeA RomInode is created for each file in the Rom file system.
MprSignalInfoPer signal structure.
MprSignalProcSignal callback procedure.
MprSignalServiceSignal service control.
MprSocketPrebindCallback before binding a socket.
MprSocketProcSocket I/O callback procedure.
MprSocketProviderSocket service provider interface.
MprSocketServiceMpr socket service class.
MprSortProcQuicksort callback function.
MprSpinMultithreading spin lock control structure.
MprSslCallback function for SNI connections.
MprTerminatorService shutdown notifier.
MprThreadLocalThread local data storage.
MprThreadProcThread main procedure.
MprThreadServiceThread service.
MprTicksElapsed time data type.
MprWaitServiceWait Service.
MprWorkerProcWorker thread callback signature.
MprWorkerServiceWorker Thread Service.
MprWorkerStatsStatistics for Workers.
MprXmlHandlerXML callback handler.
MprXmlInputStreamXML input stream function.
SocketArgument for sockets.
size_tUnsigned integral type.

Defines

#defineME_MAX_EVENTS   32
 Maximum number of notifier events.
#defineME_MPR_ALLOC_TRACE   0
 Trace to stdout.
#defineME_MPR_LOGGING   1
 Default for logging is "on".
#defineME_MPR_MAX_PASSWORD   256
 Max password length.
#defineMPR_ALLOC_HOLD   0x4
 Allocate and hold immune from GC until mprRelease.
#defineMPR_ALLOC_MANAGER   0x1
 Reserve room for a manager.
#defineMPR_ALLOC_PAD_MASK   0x1
 Flags that impact padding.
#defineMPR_ALLOC_POLICY_EXIT   3
 Exit the app if maxHeap exceeded.
#defineMPR_ALLOC_POLICY_NOTHING   0
 Do nothing.
#defineMPR_ALLOC_POLICY_PRUNE   1
 Prune all non-essential memory and continue.
#defineMPR_ALLOC_POLICY_RESTART   2
 Gracefully restart the app if memory maxHeap level is exceeded.
#defineMPR_ALLOC_ZERO   0x2
 Zero memory.
#defineMPR_ARGV_ARGS_ONLY   0x1
 Command is missing program name.
#defineMPR_BACKGROUND_PRIORITY   15
 May only get CPU if idle.
#defineMPR_CACHE_ADD   0x2
 mprWriteCache option to add key only if not already existing.
#defineMPR_CACHE_APPEND   0x8
 mprWriteCache option to set and append if already existing.
#defineMPR_CACHE_NOTIFY_CREATE   1
 Item has been created.
#defineMPR_CACHE_NOTIFY_REMOVE   2
 Item is about to be removed.
#defineMPR_CACHE_NOTIFY_UPDATE   4
 Item has been updated.
#defineMPR_CACHE_PREPEND   0x10
 mprWriteCache option to set and prepend if already existing.
#defineMPR_CACHE_SET   0x4
 mprWriteCache option to update key value, create if required.
#defineMPR_CACHE_SHARED   0x1
 Use shared cache for mprCreateCache()
#defineMPR_CG_DEFAULT   0x0
 mprGC flag to run GC if necessary.
#defineMPR_CMD_DETACH   0x4
 mprRunCmd flag to detach the child process and don't wait.
#defineMPR_CMD_ERR   0x4000
 mprRunCmd flag to capture stdout.
#defineMPR_CMD_EXACT_ENV   0x8
 mprRunCmd flag to use the exact environment (no inherit from parent).
#defineMPR_CMD_IN   0x1000
 mprRunCmd flag to connect to stdin.
#defineMPR_CMD_NEW_SESSION   0x1
 mprRunCmd flag to create a new session on unix.
#defineMPR_CMD_OUT   0x2000
 mprRunCmd flag to capture stdout.
#defineMPR_CMD_SHOW   0x2
 mprRunCmd flag to show the window of the created process on windows.
#defineMPR_CMD_STDERR   2
 Stderr for the client side.
#defineMPR_CMD_STDIN   0
 Stdout for the client side.
#defineMPR_CMD_STDOUT   1
 Stdin for the client side.
#defineMPR_CMD_VXWORKS_EOF   "_ _EOF_ _"
 Special string for VxWorks CGI to emit to signal EOF.
#defineMPR_CMD_VXWORKS_EOF_LEN   9
 Length of MPR_CMD_VXWORKS_EOF.
#defineMPR_CREATED   1
 Applicationa and MPR services started.
#defineMPR_CRITICAL_PRIORITY   99
 May not yield.
#defineMPR_DAEMON   0x10
 Make the process a daemon.
#defineMPR_DECODE_TOKEQ   1
 Decode base 64 blocks up to a NULL or equals.
#defineMPR_DEFAULT_DATE   "%a %b %d %T %Y %Z"
 Default date format used in mprFormatLocalTime/mprFormatUniversalTime when no format supplied.
#defineMPR_DEFAULT_MAX_THREADS   5
 Default max threads.
#defineMPR_DEFAULT_MIN_THREADS   0
 Default min threads.
#defineMPR_DELAY_GC_THREAD   0x8
 Delay starting the GC thread.
#defineMPR_DESTROYED   6
 Application and MPR object destroyed
#defineMPR_DESTROYING   5
 Destroying core MPR services and releasing memory.
#defineMPR_DISABLE_GC   0x1
 Disable GC.
#defineMPR_DISPATCHER_AUTO   0x8
 Dispatcher was auto created in response to accept event.
#defineMPR_DISPATCHER_COMPLETE   0x10
 Test operation is complete.
#defineMPR_DISPATCHER_DESTROYED   0x4
 Dispatcher has been destroyed.
#defineMPR_DISPATCHER_IMMEDIATE   0x1
 Dispatcher should run using the service events thread.
#defineMPR_DISPATCHER_WAITING   0x2
 Dispatcher waiting for an event in mprWaitForEvent.
#defineMPR_ERR   -1
 Default error code.
#defineMPR_ERR_ABORTED   -2
 Action aborted.
#defineMPR_ERR_ALREADY_EXISTS   -3
 Item already exists.
#defineMPR_ERR_BAD_ARGS   -4
 Bad arguments or paramaeters.
#defineMPR_ERR_BAD_FORMAT   -5
 Bad input format.
#defineMPR_ERR_BAD_HANDLE   -6
 Bad file handle.
#defineMPR_ERR_BAD_STATE   -7
 Module is in a bad state.
#defineMPR_ERR_BAD_SYNTAX   -8
 Input has bad syntax.
#defineMPR_ERR_BAD_TYPE   -9
 Bad object type.
#defineMPR_ERR_BAD_VALUE   -10
 Bad or unexpected value.
#defineMPR_ERR_BASE   -1
 Base error code.
#defineMPR_ERR_BUSY   -11
 Resource is busy.
#defineMPR_ERR_CANT_ACCESS   -12
 Cannot access the file or resource.
#defineMPR_ERR_CANT_ALLOCATE   -13
 Cannot allocate resource.
#defineMPR_ERR_CANT_COMPLETE   -14
 Operation cannot complete.
#defineMPR_ERR_CANT_CONNECT   -15
 Cannot connect to network or resource.
#defineMPR_ERR_CANT_CREATE   -16
 Cannot create the file or resource.
#defineMPR_ERR_CANT_DELETE   -17
 Cannot delete the resource.
#defineMPR_ERR_CANT_FIND   -18
 Cannot find resource.
#defineMPR_ERR_CANT_INITIALIZE   -19
 Cannot initialize resource.
#defineMPR_ERR_CANT_LOAD   -20
 Cannot load the resource.
#defineMPR_ERR_CANT_OPEN   -21
 Cannot open the file or resource.
#defineMPR_ERR_CANT_READ   -22
 Cannot read from the file or resource.
#defineMPR_ERR_CANT_WRITE   -23
 Cannot write to the file or resource.
#defineMPR_ERR_DELETED   -24
 Resource has been deleted.
#defineMPR_ERR_MEMORY   -25
 Memory allocation error.
#defineMPR_ERR_NETWORK   -26
 Underlying network error.
#defineMPR_ERR_NOT_INITIALIZED   -27
 Module or resource is not initialized.
#defineMPR_ERR_NOT_READY   -28
 Resource is not ready.
#defineMPR_ERR_OK   0
 Success.
#defineMPR_ERR_READ_ONLY   -29
 The operation timed out.
#defineMPR_ERR_TIMEOUT   -30
 Operation exceeded specified time allowed.
#defineMPR_ERR_TOO_MANY   -31
 Too many requests or resources.
#defineMPR_ERR_WONT_FIT   -32
 Requested operation won't fit in available space.
#defineMPR_ERR_WOULD_BLOCK   -33
 Blocking operation would block.
#defineMPR_EVENT_ALWAYS   0x20
 Always invoke the callback even if the event not run
#defineMPR_EVENT_ASYNC   1
 Windows async select.
#defineMPR_EVENT_CONTINUOUS   0x1
 Timer event runs is automatically rescheduled.
#defineMPR_EVENT_DONT_QUEUE   0x4
 Don't queue the event.
#defineMPR_EVENT_EPOLL   2
 epoll_wait.
#defineMPR_EVENT_KQUEUE   3
 BSD kqueue.
#defineMPR_EVENT_PRIORITY   50
 Normal priority.
#defineMPR_EVENT_QUICK   0x2
 Execute inline without executing via a thread.
#defineMPR_EVENT_RUNNING   0x10
 Event currently executing.
#defineMPR_EVENT_SELECT   4
 traditional select().
#defineMPR_EVENT_STATIC_DATA   0x8
 Event data is permanent and should not be marked by GC.
#defineMPR_EVENT_TIME_SLICE   20 /* 20 msec */
 Events.
#defineMPR_EXIT_ABORT   0x1
 Abort everything and call exit().
#defineMPR_EXIT_NORMAL   0x0
 Normal (graceful) exit.
#defineMPR_EXIT_RESTART   0x4
 Restart after exiting.
#defineMPR_EXIT_SAFE   0x2
 Graceful shutdown only if all requests complete.
#defineMPR_EXIT_TIMEOUT   -1
 Use timeout specified via mprSetExitTimeout
#defineMPR_GC_COMPLETE   0x4
 mprGC flag to force start a GC and wait until the GC cycle fully completes including sweep phase.
#defineMPR_GC_FORCE   0x1
 mprGC flag to force start a GC sweep whether it is required or not.
#defineMPR_GC_NO_BLOCK   0x2
 mprGC flag to run GC if ncessary and return without yielding.
#defineMPR_HASH_CASELESS   0x10
 Key comparisons ignore case.
#defineMPR_HASH_MANAGED_KEYS   0x100
 Keys are managed - mark but don't dup.
#defineMPR_HASH_MANAGED_VALUES   0x200
 Values are managed - mark but don't dup.
#defineMPR_HASH_STABLE   0x800
 Contents are stable or only accessed by one thread.
#defineMPR_HASH_STATIC_KEYS   0x40
 Keys are permanent - don't dup or mark.
#defineMPR_HASH_STATIC_VALUES   0x80
 Values are permanent - don't mark.
#defineMPR_HASH_UNICODE   0x20
 Hash keys are unicode strings.
#defineMPR_HASH_UNIQUE   0x400
 Add to existing will fail.
#defineMPR_HTTP_DATE   "%a, %d %b %Y %T GMT"
 Date format for use in HTTP (headers).
#defineMPR_JSON_APPEND   0x4
 Default to append to existing '+' (default).
#defineMPR_JSON_ARRAY   0x2
 The property is an array.
#defineMPR_JSON_COMBINE   0x1
 Combine properties using '+' '-' '=' '?' prefixes.
#defineMPR_JSON_CREATE   0x10
 Create if not already existing '?'.
#defineMPR_JSON_DATA_TYPE   0xFF8
 Mask for core type of obj (obj|array|value).
#defineMPR_JSON_ENCODE_TYPES   0x8
 Encode dates and regexp with {type:date} or {type:regexp}.
#defineMPR_JSON_FALSE   0x8
 The property is false.
#defineMPR_JSON_NULL   0x10
 The property is null.
#defineMPR_JSON_NUMBER   0x20
 The property is a number.
#defineMPR_JSON_OBJ   0x1
 The property is an object.
#defineMPR_JSON_OBJ_TYPE   0x7
 Mask for core type of obj (obj|array|value).
#defineMPR_JSON_OVERWRITE   0x2
 Default to overwrite existing properties '='.
#defineMPR_JSON_PRETTY   0x1
 Serialize output in a more human readable, multiline "pretty" format.
#defineMPR_JSON_QUOTES   0x2
 Serialize output quoting keys.
#defineMPR_JSON_REGEXP   0x40
 The property is a regular expression.
#defineMPR_JSON_REPLACE   0x8
 Replace existing properties '-'.
#defineMPR_JSON_STRING   0x80
 The property is a string.
#defineMPR_JSON_STRINGS   0x4
 Emit all values as quoted strings.
#defineMPR_JSON_TRUE   0x100
 The property is true.
#defineMPR_JSON_UNDEFINED   0x200
 The property is undefined.
#defineMPR_JSON_VALUE   0x4
 The property is a value (false|true|null|undefined|regexp|number|string)
#defineMPR_LIST_STABLE   0x40
 Contents are stable or only accessed by one thread.
#defineMPR_LIST_STATIC_VALUES   0x20
 Flag for mprCreateList when values are permanent.
#defineMPR_LOCAL_TIMEZONE   MAXINT
 Constants for mprParseTime.
#defineMPR_LOG_ANEW   0x1
 Start anew on restart after backup.
#defineMPR_LOG_CMDLINE   0x4
 Command line log switch uses.
#defineMPR_LOG_CONFIG   0x2
 Show the configuration at the start of the log.
#defineMPR_LOG_DATE   "%D %T"
 Date for use in log files (compact).
#defineMPR_LOG_DETAILED   0x8
 Use detailed log formatting with timestamps and tags.
#defineMPR_LOG_HEXDUMP   0x10
 Emit hexdump.
#defineMPR_LOG_TAGGED   0x10
 Use tagged message formatting.
#defineMPR_MANAGE_FREE   0x1
 Block being freed.
#defineMPR_MANAGE_MARK   0x2
 Block being marked by GC.
#defineMPR_MAX_FILE   256
 Maximum number of files to close when forking.
#defineMPR_MEM_FAIL   0x4
 Memory allocation failed - immediate exit.
#defineMPR_MEM_LIMIT   0x2
 Memory use exceeds memory limit - invoking policy.
#defineMPR_MEM_TOO_BIG   0x8
 Memory allocation request is too big - immediate exit.
#defineMPR_MEM_WARNING   0x1
 Memory use exceeds warnHeap level limit.
#defineMPR_MIN_TIME_FOR_GC   2
 Wait till 2 milliseconds of idle time possible.
#defineMPR_MODULE_DATA_MANAGED   0x8
 Module.moduleData is managed.
#defineMPR_MODULE_LOADED   0x4
 Dynamic module loaded.
#defineMPR_MODULE_STARTED   0x1
 Module stared.
#defineMPR_MODULE_STOPPED   0x2
 Module stopped.
#defineMPR_NO_WINDOW   0x4
 Don't create a windows Window.
#defineMPR_NORMAL_PRIORITY   50
 Normal (default) priority.
#defineMPR_NOT_ALL   0x20
 Don't invoke all destructors when terminating.
#defineMPR_OBJ_HASH   0x1
 Object is a hash.
#defineMPR_OBJ_LIST   0x1
 Object is a hash.
#defineMPR_PATH_DEPTH_FIRST   0x2
 Flag for mprGetPathFiles to do a depth-first traversal.
#defineMPR_PATH_DESCEND   0x1
 Flag for mprGetPathFiles to traverse subdirectories.
#defineMPR_PATH_INC_HIDDEN   0x4
 Flag for mprGetPathFiles to include hidden files.
#defineMPR_PATH_NO_DIRS   0x8
 Flag for mprGetPathFiles to exclude subdirectories.
#defineMPR_PATH_RELATIVE   0x10
 Flag for mprGetPathFiles to return paths relative to the directory.
#defineMPR_PROTO_ALL   0x6B
 All protocols.
#defineMPR_PROTO_SSLV2   0x1
 SSL V2 protocol.
#defineMPR_PROTO_SSLV3   0x2
 SSL V3 protocol.
#defineMPR_PROTO_TLSV1_0   0x8
 TLS V1.0 protocol.
#defineMPR_PROTO_TLSV1_1   0x10
 TLS V1.1 protocol.
#defineMPR_PROTO_TLSV1_2   0x20
 TLS V1.2 protocol.
#defineMPR_PROTO_TLSV1_3   0x40
 TLS V1.3 protocol.
#defineMPR_READABLE   0x2
 Read event mask.
#defineMPR_REQUEST_PRIORITY   50
 Normal priority.
#defineMPR_RFC3399_DATE   "%FT%TZ"
 Date format for RFC 3399 for use in HTML 5.
#defineMPR_RFC_DATE   "%a, %d %b %Y %T %Z"
 Format a date according to RFC822: (Fri, 07 Jan 2003 12:12:21 PDT).
#defineMPR_SERVICE_NO_BLOCK   0x4
 Do not block in mprServiceEvents.
#defineMPR_SERVICE_NO_GC   0x8
 Don't run GC.
#defineMPR_SIGNAL_AFTER   0x2
 Flag to mprAddSignalHandler to run handler after existing handlers.
#defineMPR_SIGNAL_BEFORE   0x1
 Flag to mprAddSignalHandler to run handler before existing handlers.
#defineMPR_SOCKET_BLOCK   0x1
 Use blocking I/O.
#defineMPR_SOCKET_BROADCAST   0x2
 Broadcast mode.
#defineMPR_SOCKET_BUFFERED_READ   0x800
 Socket has buffered read data (in SSL stack).
#defineMPR_SOCKET_BUFFERED_WRITE   0x1000
 Socket has buffered write data (in SSL stack).
#defineMPR_SOCKET_CERT_ERROR   0x10000
 Error when validating peer certificate.
#defineMPR_SOCKET_CLOSED   0x4
 MprSocket has been closed.
#defineMPR_SOCKET_CONNECTING   0x8
 MprSocket is connecting.
#defineMPR_SOCKET_DATAGRAM   0x10
 Use datagrams.
#defineMPR_SOCKET_DISCONNECTED   0x4000
 The mprDisconnectSocket has been called.
#defineMPR_SOCKET_EOF   0x20
 Seen end of file.
#defineMPR_SOCKET_GRACEFUL   1
 Do a graceful shutdown.
#defineMPR_SOCKET_HANDSHAKING   0x8000
 Doing an SSL handshake.
#defineMPR_SOCKET_LISTENER   0x40
 MprSocket is server listener.
#defineMPR_SOCKET_NODELAY   0x100
 Disable Nagle algorithm.
#defineMPR_SOCKET_NOREUSE   0x80
 Don't set SO_REUSEADDR option.
#defineMPR_SOCKET_SERVER   0x400
 Socket is on the server-side.
#defineMPR_SOCKET_THREAD   0x200
 Process callbacks on a worker thread.
#defineMPR_STARTED   2
 Applicationa and MPR services started.
#defineMPR_STOPPED   4
 App is idle and now stopped.
#defineMPR_STOPPING   3
 App has been instructed to shutdown.
#defineMPR_TIMEOUT_GC_SYNC   100
 Short wait period for threads to synchronize.
#defineMPR_TIMEOUT_LINGER   2000
 Close socket linger timeout.
#defineMPR_TIMEOUT_NAP   20
 Short pause.
#defineMPR_TIMEOUT_NO_BUSY   1000
 Wait period to minimize CPU drain.
#defineMPR_TIMEOUT_PRUNER   120000
 Time between worker thread pruner runs (2 min).
#defineMPR_TIMEOUT_START_TASK   10000
 Time to start tasks running.
#defineMPR_TIMEOUT_STOP   30000
 Default wait when stopping resources (30 sec).
#defineMPR_TIMEOUT_STOP_TASK   10000
 Time to stop or reap tasks (vxworks).
#defineMPR_TIMEOUT_WORKER   60000
 Prune worker that has been idle for 1 min.
#defineMPR_TRIM_BOTH   0x3
 Flag for strim to trim from both the start and the end of the string.
#defineMPR_TRIM_END   0x2
 Flag for strim to trim from the end of the string.
#defineMPR_TRIM_START   0x1
 Flag for strim to trim from the start of the string.
#defineMPR_USER_EVENTS_THREAD   0x2
 User will explicitly manage own mprServiceEvents calls.
#defineMPR_UTC_TIMEZONE   0
 Use UTC timezone.
#defineMPR_WAIT_IMMEDIATE   0x4
 Wait handler flag to immediately service event on same thread.
#defineMPR_WAIT_NEW_DISPATCHER   0x2
 Wait handler flag to create a new dispatcher for each I/O event.
#defineMPR_WAIT_NOT_SOCKET   0x8
 I/O file descriptor is not a socket - windows will ignore.
#defineMPR_WAIT_RECALL_HANDLER   0x1
 Wait handler flag to recall the handler asap.
#defineMPR_WORKER_BUSY   0x1
 Worker currently running to a callback.
#defineMPR_WORKER_IDLE   0x4
 Worker is sleeping (idle) on idleCond.
#defineMPR_WORKER_PRIORITY   50
 Normal priority.
#defineMPR_WORKER_PRUNED   0x2
 Worker has been pruned and will be terminated.
#defineMPR_WRITABLE   0x4
 Write event mask.
#defineMPR_XML_AFTER_LS   2
 Seen "<"
#defineMPR_XML_ATT_EQ   6
 Seen "<tag att" =
#defineMPR_XML_ATT_NAME   5
 Seen "<tag att"
#defineMPR_XML_BEGIN   1
 Before next tag
#defineMPR_XML_CDATA   13
 Seen "<![CDATA[" U
#defineMPR_XML_COMMENT   3
 Seen "<!—" (usr) U
#defineMPR_XML_ELT_DATA   10
 Seen "<tag>....<" U
#defineMPR_XML_ELT_DEFINED   9
 Seen "<tag...>" U
#defineMPR_XML_END_ELT   11
 Seen "<tag>....</tag>" U
#defineMPR_XML_EOF   -2
 End of input.
#defineMPR_XML_ERR   -1
 Error.
#defineMPR_XML_NEW_ATT   7
 Seen "<tag att = "val" U
#defineMPR_XML_NEW_ELT   4
 Seen "<tag" (usr) U
#defineMPR_XML_PI   12
 Seen "<?processingInst" U
#defineMPR_XML_SOLO_ELT_DEFINED   8
 Seen "<tag../>" U
#defineMPR_YIELD_COMPLETE   0x1
 mprYield flag to wait until the GC entirely completes including sweep phase.
#defineMPR_YIELD_DEFAULT   0x0
 mprYield flag if GC is required, yield and wait for mark phase to coplete, otherwise return without blocking.
#defineMPR_YIELD_STICKY   0x2
 mprYield flag to yield and remain yielded until reset.

Mpr

Mpr

Primary MPR application control structure.

Description:
The Mpr structure stores critical application state information.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
API Stability:
Internal.
Fields:
cchar *appDir Path of directory containing app executable.
cchar *appPath Path name of application executable.
void *appwebService Appweb service object.
char **argBuf Space for allocated argv.
intargc Count of command line args.
cchar **argv Application command line args (not alloced).
struct MprCmdService *cmdService Command service object.
MprCond *cond Sync after starting events thread.
booldebugMode Run in debug mode (no timers).
struct MprDispatcher *dispatcher Primary dispatcher.
char *domainName Domain portion.
void *ediService EDI object.
void *ejsService Ejscript service.
char *emptyString "" string.
void *espService ESP service object.
inteventing Servicing events thread is active.
struct MprEventService *eventService Event service object.
intexitStrategy How to exit the app.
MprTicksexitTimeout Request timeout when exiting.
MprList *fileSystems File system objects.
intflags Misc flags.
inthasError Mpr has an initialization error.
MprHeap *heap Memory heap control.
char *hostName Host name (fully qualified name).
void *httpService Http service object.
MprIdleCallbackidleCallback Invoked to determine if the process is idle.
char *ip Public IP Address.
MprHash *keys Simple key/value store.
intlogBackup Number of log files preserved when backing up.
MprFile *logFile Log file.
MprLogHandlerlogHandler Current log handler callback.
intlogLevel Log trace level.
cchar *logPath Log path name.
ssizelogSize Maximum log size.
MprOsThreadmainOsThread Main OS thread ID.
MprHash *mimeTypes Table of mime types.
struct MprModuleService *moduleService Module service object.
MprMutex *mutex Thread synchronization used for global lock.
char *name Product name.
struct MprDispatcher *nonBlock Nonblocking dispatcher.
char *oneString "1" string.
struct MprOsService *osService O/S service object.
char *pathEnv Cached PATH env var. Used by MprCmd.
MprFileSystem *romfs Rom file system object.
char *serverName Server name portion (no domain).
MprTicksshutdownStarted When the shutdown started.
struct MprSignalService *signalService Signal service object.
struct MprSocketService *socketService Socket service object.
MprSpin *spin Quick thread synchronization.
MprTimestart When the MPR started.
MprFile *stdError Standard error file.
MprFile *stdInput Standard input file.
MprFile *stdOutput Standard output file.
MprCond *stopCond Sync for stopping.
MprList *terminators Termination callbacks.
struct MprThreadService *threadService Thread service object.
MprHash *timeTokens Date/Time parsing tokens.
char *title Product title.
intverifySsl Default verification of SSL certificates.
char *version Product version.
struct MprWaitService *waitService IO Waiting service object.
struct MprWorkerService *workerService Worker service object.
PUBLIC void void assert (bool cond)
PUBLIC void void mprAddTerminator (MprTerminator terminator)

Add a service terminator.

Description:
Services may create shutdown notifiers called terminators that are informed when the application commences a shutdown. The terminator may be invoked several times and the service should take appropriate action based on the MPR state.

If the state parameter is set to MPR_STOPPING, the service should not accept any new requests, but otherwise not take any destructive actions. Note this state is required to be reversible if the shutdown is cancelled.

If the state is MPR_STOPPED, the service should cancel all running requests, close files and connections and release all resources. This state is not reversible.

This exitStrategy parameter is a flags word that defines the shutdown exit strategy. See mprShutdown for details.

Services may also call mprShouldDenyNewRequests to test if the MPR state is MPR_STOPPING and mprShouldAbortRequests if the state is MPR_STOPPED.
Parameters:
terminatorMprTerminator callback function.
API Stability:
Stable.
See Also:
mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC void void mprBreakpoint (void )
PUBLIC bool bool mprCancelShutdown (void )

Cancel a shutdown request.

Description:
A graceful shutdown request initiated via mprShutdown may be cancelled if the shutdown is still in progress and has not passed the point of no return. If the MPR is still in the MPR_STOPPING state, the shutdown may be cancelled. See mprGetState
Returns:
True if the shutdown can be cancelled. Returns false if a shutdown has not been requested or if the shutdown has advanced past the point of no return.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC bool bool mprCheckPassword (cchar *plainTextPassword, cchar *passwordHash)
PUBLIC Mpr,* Mpr* mprCreate (int argc, char **argv, int flags)

Initialize the application by creating an instance of the MPR.

Description:
Initializes the MPR and creates an Mpr control object. The Mpr Object manages all MPR facilities and services. This must be called before using any MPR API. When processing is complete, you should call mprDestroy before exiting the application.
Parameters:
argcCount of command line args.
argvCommand line arguments for the application. Arguments may be passed into the Mpr for retrieval by the unit test framework.
flagsSet MPR_USER_EVENTS_THREAD if you will manage calling mprServiceEvents manually if required. There are three styles of MPR applications with respect to servicing events:

1) Applications that don't require servicing events for I/O, commands or timers

2) Applications that call mprServiceEvents directly from their main program

3) Applications that have a dedicated service events thread

Applications that do not perform I/O, run commands or create events may not need a service events thread. While creating one will do no harm, performance may be enhanced for these applications by specifying MPR_USER_EVENTS_THREAD.

Applications that have not forground processing requirements may invoke mprServiceEvents from their main program instead of creating a service events thread. This saves one thread.

The default is to create a service events thread so the full scope of MPR services are supported.
Returns:
Returns a pointer to the Mpr object.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC int int mprCreateOsService (void )
PUBLIC char,* char* mprCryptPassword (cchar *password, cchar *salt, int rounds)
PUBLIC int int mprDaemon (void )
PUBLIC char,* char* mprDecode64 (cchar *str)
PUBLIC char,* char* mprDecode64Block (cchar *buf, ssize *len, int flags)
PUBLIC bool bool mprDestroy (void )

Destroy the MPR and all services using the MPR.

Description:
This call terminates the MPR and all services.

An application initializes the MPR by calling mprCreate. This creates the Mpr object, the memory allocator, garbage collector and other services. An application exits by invoking mprDestroy or by calling mprShutdown then mprDestroy.

There are two styles of MPR applications with respect to shutdown:

1) Applications that have a dedicated service events thread.

2) Applications that call mprServiceEvents directly from their main program.

Applications that have a service events thread can call mprDestroy directly from their main program when ready to exit. Applications that call mprServiceEvents from their main program will typically have some other MPR thread call mprShutdown to initiate a shutdown sequence. This will stop accepting new requests or connections and when the application is idle, the mprServiceEvents routine will return and then the main program can call then call mprDestroy.

Once the shutdown conditions are satisfied, a thread executing mprServiceEvents will return from that API and then the application should call mprDestroy and exit().

If an application needs to tailor how it exits with respect to current requests, use mprShutdown first to specify a shutdown strategy.
Returns:
True if the MPR can be destroyed. Returns false if the exit strategy MPR_EXIT_SAFE has been defined via mprShutdown and current requests have not completed within the exit timeout period defined by mprSetExitTimeout. In this case, the shutdown is cancelled and normal operations continue.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC char,* char* mprEmptyString (void )
PUBLIC char,* char* mprEncode64 (cchar *str)
PUBLIC char,* char* mprEncode64Block (cchar *buf, ssize len)
PUBLIC char,* char* mprEscapeCmd (cchar *cmd, int escChar)
PUBLIC char,* char* mprEscapeHtml (cchar *html)
PUBLIC char,* char* mprEscapeSQL (cchar *cmd)
PUBLIC cchar,* cchar* mprGetAppDir (void )
PUBLIC cchar,* cchar* mprGetAppName (void )
PUBLIC cchar,* cchar* mprGetAppPath (void )
PUBLIC cchar,* cchar* mprGetAppTitle (void )
PUBLIC cchar,* cchar* mprGetAppVersion (void )
PUBLIC bool bool mprGetCmdlineLogging (void )
PUBLIC bool bool mprGetDebugMode (void )
PUBLIC cchar,* cchar* mprGetDomainName (void )
PUBLIC int int mprGetEndian (void )
PUBLIC int int mprGetError (void )
PUBLIC int int mprGetExitStatus (void )
PUBLIC cchar,* cchar* mprGetHostName (void )
PUBLIC cchar,* cchar* mprGetIpAddr (void )
PUBLIC void,* void* mprGetKey (cchar *key)
PUBLIC int int mprGetLogLevel (void )
PUBLIC char,* char* mprGetMD5 (cchar *str)
PUBLIC char,* char* mprGetMD5WithPrefix (cchar *buf, ssize len, cchar *prefix)
PUBLIC Mpr,* Mpr* mprGetMpr (void )
PUBLIC int int mprGetOsError (void )
PUBLIC char,* char* mprGetPassword (cchar *prompt)
PUBLIC int int mprGetRandomBytes (char *buf, ssize size, bool block)
PUBLIC char,* char* mprGetRandomString (ssize size)
PUBLIC cchar,* cchar* mprGetServerName (void )
PUBLIC char,* char* mprGetSHA (cchar *str)
PUBLIC char,* char* mprGetSHABase64 (cchar *str)
PUBLIC char,* char* mprGetSHAWithPrefix (cchar *buf, ssize len, cchar *prefix)
PUBLIC int int mprGetState (void )
PUBLIC bool bool mprIsDestroyed (void )
PUBLIC bool bool mprIsDestroying (void )
PUBLIC bool bool mprIsIdle (bool traceRequests)

Determine if the App is idle.

Description:
This call returns true if the App is not currently servicing any requests. By default this returns true if the MPR dispatcher, worker thread and command subsytems are idle. Callers can replace or augment the standard idle testing by definining a new idle callback via mprSetIdleCallback.

Note: this routine tests for worker threads but ignores other threads created via mprCreateThread
Parameters:
traceRequestsIf true, emit trace regarding running requests.
Returns:
True if the App are idle.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC bool bool mprIsStopped (void )

Test if the application is stopped If this routine returns true, the application shutdown has passed the point of no return.

No new requests should be accepted and current requests should be aborted. Use mprIsStopping to test if shutdown has been initiated but current requests may continue. Use mprIsDestroyed to test if the application has completed its shutdown
Returns:
True if the application is in the process of exiting.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC bool bool mprIsStopping (void )
PUBLIC int int mprMakeArgv (cchar *command, cchar ***argv, int flags)

Make a argv style array of command arguments.

Description:
The given command is parsed and broken into separate arguments and returned in a null-terminated, argv array. Arguments in the command may be quoted with single or double quotes to group words into one argument. Use back-quote "\\" to escape quotes. This routine allocates memory and must not be called before mprCreate. Consider mprParseArgs if you need to convert a command line before calling mprCreate
Parameters:
commandCommand string to parse.
argvOutput parameter containing the parsed arguments.
flagsSet to MPR_ARGV_ARGS_ONLY if the command string does not contain a program name. In this case, argv[0] will be set to "".
Returns:
The count of arguments in argv.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC char,* char* mprMakePassword (cchar *password, int saltLength, int rounds)
PUBLIC char,* char* mprMakeSalt (ssize size)
PUBLIC void void mprNap (MprTicks msec)
PUBLIC int int mprParseArgs (char *command, char **argv, int maxArgs)

Make a argv style array of command arguments.

Description:
The given command is parsed and broken into separate arguments and returned in a null-terminated, argv array. Arguments in the command may be quoted with single or double quotes to group words into one argument. Use back-quote "\\" to escape quotes. This routine modifies supplied command parameter and does not allocate any memory and may be used before mprCreate is invoked.
Parameters:
commandCommand string to parse.
argvArray for the arguments.
maxArgsSize of the argv array.
Returns:
The count of arguments in argv.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC int int mprRandom (void )
PUBLIC void void mprRestart (void )

Restart the application.

Description:
This call immediately restarts the application. The standard input, output and error I/O channels are preserved. All other open file descriptors are closed.

If the application is started via a monitoring launch daemon such as launchd or appman, the application should not use this API, but rather defer to the launch daemon to restart the application. In that case, the application should simply do a shutdown via mprShutdown and/or mprDestroy
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC bool bool mprServicesAreIdle (bool traceRequests)
PUBLIC int int mprSetAppName (cchar *name, cchar *title, cchar *version)
PUBLIC void void mprSetAppPath (cchar *path)
PUBLIC bool bool mprSetCmdlineLogging (bool on)

Set if command line logging was requested.

Description:
Logging may be initiated by invoking an MPR based program with a "—log" switch. This API assists programs to tell the MPR that command line logging has been used.
Parameters:
onSet to true to indicate command line logging is being used.
Returns:
True if command line logging was enabled before this call.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC void void mprSetDebugMode (bool on)
PUBLIC void void mprSetDomainName (cchar *s)
PUBLIC void void mprSetEnv (cchar *key, cchar *value)
PUBLIC void void mprSetError (int error)
PUBLIC void void mprSetExitStatus (int status)
PUBLIC void void mprSetExitTimeout (MprTicks timeout)

Set the exit timeout for a shutdown.

Description:
A shutdown waits for existing requests to complete before exiting. After this timeout has expired, the application will either invoke exit() or cancel the shutdown depending on whether MPR_EXIT_SAFE is defined in the exit strategy via mprShutdown. The default exit timeout is zero.
Parameters:
timeoutTime in milliseconds to wait for current requests to complete and the application to become idle.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprShutdown, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC void void mprSetFilesLimit (int limit)
PUBLIC void void mprSetHostName (cchar *s)
PUBLIC MprIdleCallback MprIdleCallback mprSetIdleCallback (MprIdleCallback idleCallback)
PUBLIC void void mprSetIpAddr (cchar *ip)
PUBLIC void void mprSetKey (cchar *key, void *value)
PUBLIC void void mprSetOsError (int error)
PUBLIC void void mprSetServerName (cchar *s)
PUBLIC bool bool mprShouldAbortRequests (void )
PUBLIC bool bool mprShouldDenyNewRequests (void )
PUBLIC void void mprShutdown (int exitStrategy, int status, MprTicks timeout)

Initiate shutdown of the MPR and application.

Description:
Commence shutdown of the application according to the shutdown policy defined by the "exitStrategy" parameter. An application may call this routine from any thread to request the application exit. Depending on the exitStrategy, this may be an abortive or graceful exit. A desired application exit status code can defined to indicate the cause of the shutdown.

Once called, this routine will set the MPR execution state to MPR_EXIT_STOPPING. Services should detect this by calling mprShouldDenyNewRequests before accepting new connections or requests, but otherwise, services should not take any destructive actions until the MPR state is advanced to MPR_EXIT_STOPPED by mprDestroy. This state can be detected by calling mprShouldAbortRequests. Users can invoke mprCancelShutdown to resume normal operations provided mprDestroy has not proceeded past the point of no return when destructive termination actions are commenced.

Applications that have a user events thread and call mprServiceEvents from their main program, will typically invoke mprShutdown from some other MPR thread to initiate the shutdown. When running requests have completed, or when the shutdown timeout expires (MPR->exitTimeout), the call to mprServiceEvents in the main program will return and the application can then call mprDestroy to complete the shutdown.

Note: This routine starts the shutdown process but does not perform any destructive actions.
Parameters:
exitStrategyShutdown policy. If the MPR_EXIT_ABORT flag is specified, the application will immediately call exit() and will terminate without waiting for current requests to complete. This is not recommended for normal operation as data may be lost.

If MPR_EXIT_SAFE is defined, the shutdown will be cancelled if all requests do not complete before the exit timeout defined via mprSetExitTimeout expires.

Define the MPR_EXIT_RESTART flag for the application to automatically restart after exiting. Do not use this option if the application is using a watchdog/angel process to automatically restart the application (such as appman by appweb).
statusProposed exit status to use when the application exits. See mprGetExitStatus
timeoutExit timeout in milliseconds to wait for current requests to complete. If set to -1, for the default exit timeout.
API Stability:
Stable.
See Also:
mprAddTerminator, mprBreakpoint, mprCreate, mprCreateOsService, mprDecode64, mprDestroy, mprEmptyString, mprEncode64, mprEscapeCmd, mprGetAppDir, mprGetAppName, mprGetAppPath, mprGetAppTitle, mprGetAppVersion, mprGetCmdlineLogging, mprGetDebugMode, mprGetDomainName, mprGetEndian, mprGetError, mprGetHostName, mprGetIpAddr, mprGetLogLevel, mprGetMD5, mprGetMD5WithPrefix, mprGetOsError, mprGetRandomBytes, mprGetServerName, mprIsDestroyed, mprIsDestroying, mprIsIdle, mprIsStopping, mprMakeArgv, mprRandom, mprRestart, mprServicesAreIdle, mprSetAppName, mprSetDebugMode, mprSetDomainName, mprSetHostName, mprSetIdleCallback, mprSetIpAddr, mprSetLogLevel, mprSetServerName, mprShouldAbortRequests, mprShouldDenyNewRequests, mprSleep, mprStart, mprStartEventsThread, mprStartOsService, mprStopOsService, mprUriDecode, mprUriEncode
PUBLIC void void mprSleep (MprTicks msec)
PUBLIC int int mprStart (void )
PUBLIC int int mprStartEventsThread (void )
PUBLIC int int mprStartOsService (void )
PUBLIC void void mprStopOsService (void )
PUBLIC char,* char* mprUriDecode (cchar *uri)
PUBLIC char,* char* mprUriDecodeInSitu (char *uri)
PUBLIC char,* char* mprUriEncode (cchar *uri, int map)

MprBuf

MprBuf

Dynamic Buffer Module.

Description:
MprBuf is a flexible, dynamic growable buffer structure. It has start and end pointers to the data buffer which act as read/write pointers. Routines are provided to get and put data into and out of the buffer and automatically advance the appropriate start/end pointer. By definition, the buffer is empty when the start pointer == the end pointer. Buffers can be created with a fixed size or can grow dynamically as more data is added to the buffer.

For performance, the specification of MprBuf is deliberately exposed. All members of MprBuf are implicitly public. However, it is still recommended that wherever possible, you use the accessor routines provided.
See Also:
MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
API Stability:
Internal.
Fields:
ssizebuflen Current size of buffer.
char *data Actual buffer for data.
char *end Pointer one past the last data chr.
char *endbuf Pointer one past the end of buffer.
ssizegrowBy Next growth increment to use.
ssizemaxsize Max size the buffer can ever grow.
void *refillArg Refill arg - must be alloced memory.
MprBufProcrefillProc Auto-refill procedure.
char *start Pointer to next data char.
PUBLIC void void mprAddNullToBuf (MprBuf *buf)

Add a null character to the buffer contents.

Description:
Add a null byte but do not change the buffer content lengths. The null is added outside the "official" content length. This is useful when calling mprGetBufStart and using the returned pointer as a "C" string pointer.
Parameters:
bufBuffer created via mprCreateBuf.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC void void mprAdjustBufEnd (MprBuf *buf, ssize count)

Adjust the buffer end position.

Description:
Adjust the buffer end position by the specified amount. This is typically used to advance the end position as content is appended to the buffer. Adjusting the start or end position will change the value returned by mprGetBufLength. If using the mprPutBlock or mprPutChar routines, adjusting the end position is done automatically.
Parameters:
bufBuffer created via mprCreateBuf.
countPositive or negative count of bytes to adjust the end position.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC void void mprAdjustBufStart (MprBuf *buf, ssize count)

Adjust the buffer start position.

Description:
Adjust the buffer start position by the specified amount. This is typically used to advance the start position as content is consumed. Adjusting the start or end position will change the value returned by mprGetBufLength. If using the mprGetBlock or mprGetChar routines, adjusting the start position is done automatically.
Parameters:
bufBuffer created via mprCreateBuf.
countPositive or negative count of bytes to adjust the start position.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC char,* char* mprBufToString (MprBuf *buf)
PUBLIC void void mprCompactBuf (MprBuf *buf)
PUBLIC MprBuf,* MprBuf* mprCreateBuf (ssize initialSize, ssize maxSize)
PUBLIC void void mprFlushBuf (MprBuf *buf)
PUBLIC ssize ssize mprGetBlockFromBuf (MprBuf *buf, char *blk, ssize count)

Get a block of data from the buffer.

Description:
Get a block of data from the buffer start and advance the start position. If the requested length is greater than the available buffer content, then return whatever data is available.
Parameters:
bufBuffer created via mprCreateBuf.
blkDestination block for the read data.
countCount of bytes to read from the buffer.
Returns:
The count of bytes read into the block or -1 if the buffer is empty.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC char,* char* mprGetBuf (MprBuf *buf)

Get the origin of the buffer content storage.

Description:
Get a pointer to the start of the buffer content storage. This is always and allocated block.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
A pointer to the buffer content storage.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC char,* char* mprGetBufEnd (MprBuf *buf)

Get a reference to the end of the buffer contents.

Description:
Get a pointer to the location immediately after the end of the buffer contents.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Pointer to the end of the buffer data contents. Points to the location one after the last data byte.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize ssize mprGetBufLength (MprBuf *buf)

Get the buffer content length.

Description:
Get the length of the buffer contents. This is not the same as the buffer size which may be larger.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
The length of the content stored in the buffer in bytes.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC MprBufProc MprBufProc mprGetBufRefillProc (MprBuf *buf)
PUBLIC ssize ssize mprGetBufSize (MprBuf *buf)

Get the current size of the buffer content storage.

Description:
This returns the size of the memory block allocated for storing the buffer contents.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
The size of the buffer content storage.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize ssize mprGetBufSpace (MprBuf *buf)
PUBLIC char,* char* mprGetBufStart (MprBuf *buf)

Get the start of the buffer contents.

Description:
Get a pointer to the start of the buffer contents. Use mprGetBufLength to determine the length of the content. Use mprGetBufEnd to get a pointer to the location after the end of the content.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Pointer to the start of the buffer data contents.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprGetCharFromBuf (MprBuf *buf)
PUBLIC int int mprGrowBuf (MprBuf *buf, ssize count)

Grow the buffer.

Description:
Grow the storage allocated for content for the buffer. The new size must be less than the maximum limit specified via mprCreateBuf or mprSetBufSize
Parameters:
bufBuffer created via mprCreateBuf.
countCount of bytes by which to grow the buffer content size.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprInsertCharToBuf (MprBuf *buf, int c)

Insert a character into the buffer.

Description:
Insert a character into to the buffer prior to the current buffer start point.
Parameters:
bufBuffer created via mprCreateBuf.
cCharacter to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprLookAtLastCharInBuf (MprBuf *buf)

Peek at the last character in the buffer.

Description:
Non-destructively return the last character from just prior to the end position in the buffer. The character is returned and the end position is not altered.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprLookAtNextCharInBuf (MprBuf *buf)

Peek at the next character in the buffer.

Description:
Non-destructively return the next character from the start position in the buffer. The character is returned and the start position is not altered.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize ssize mprPutBlockToBuf (MprBuf *buf, cchar *ptr, ssize size)

Put a block to the buffer.

Description:
Append a block of data to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
ptrBlock to append.
sizeSize of block to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprPutCharToBuf (MprBuf *buf, int c)

Put a character to the buffer.

Description:
Append a character to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
cCharacter to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize ssize mprPutIntToBuf (MprBuf *buf, int64 i)

Put an integer to the buffer.

Description:
Append a integer to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
iInteger to append to the buffer.
Returns:
Number of characters added to the buffer, otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize ssize mprPutPadToBuf (MprBuf *buf, int c, ssize count)

Put padding characters to the buffer.

Description:
Append padding characters to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
cCharacter to append.
countCount of pad characters to put.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize ssize mprPutStringToBuf (MprBuf *buf, cchar *str)

Put a string to the buffer.

Description:
Append a null terminated string to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
strString to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize ssize mprPutSubStringToBuf (MprBuf *buf, cchar *str, ssize count)

Put a substring to the buffer.

Description:
Append a null terminated substring to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
strString to append.
countPut at most count characters to the buffer.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC ssize ssize mprPutToBuf (MprBuf *buf, cchar *fmt, ...)

Put a formatted string to the buffer.

Description:
Format a string and append to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
fmtPrintf style format string.
...Variable arguments for the format string.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize
PUBLIC int int mprRefillBuf (MprBuf *buf)
PUBLIC void void mprResetBufIfEmpty (MprBuf *buf)
PUBLIC void void mprSetBufMax (MprBuf *buf, ssize maxSize)
PUBLIC void void mprSetBufRefillProc (MprBuf *buf, MprBufProc fn, void *arg)

Set the buffer refill procedure.

Description:
Define a buffer refill procedure. The MprBuf module will not invoke or manage this refill procedure. It is simply stored to allow upper layers to use and provide their own auto-refill mechanism.
Parameters:
bufBuffer created via mprCreateBuf.
fnCallback function to store.
argCallback data argument.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufSize
PUBLIC int int mprSetBufSize (MprBuf *buf, ssize size, ssize maxSize)

Set the buffer size.

Description:
Set the current buffer content size and maximum size limit. Setting a current size will immediately grow the buffer to be this size. If the size is less than the current buffer size, the requested size will be ignored. ie. this call will not shrink the buffer. Setting a maxSize will define a maximum limit for how big the buffer contents can grow. Set either argument to -1 to be ignored.
Parameters:
bufBuffer created via mprCreateBuf.
sizeSize to immediately make the buffer. If size is less than the current buffer size, it will be ignored. Set to -1 to ignore this parameter.
maxSizeMaximum size the buffer contents can grow to.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Stable.
See Also:
MprBuf, MprBufProc, mprAddNullToBuf, mprAdjustBufEnd, mprAdjustBufStart, mprBufToString, mprCloneBuf, mprCompactBuf, mprCreateBuf, mprFlushBuf, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetBufStart, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutPadToBuf, mprPutStringToBuf, mprPutSubStringToBuf, mprPutToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc

MprCache

MprCache

In-memory caching.

See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
API Stability:
Internal.
Fields:
MprTickslifespan Default lifespan (msec).
ssizemaxKeys Max number of keys.
ssizemaxMem Max memory for session data.
MprMutex *mutex Cache lock.
intresolution Frequence for pruner.
struct MprCache *shared Shared common cache.
MprHash *store Key/value store.
MprEvent *timer Pruning timer.
ssizeusedMem Memory in use for keys and data.
PUBLIC MprCache,* MprCache* mprCreateCache (int options)

Create a new cache object.

Parameters:
optionsSet of option flags. Use MPR_CACHE_SHARED to select a global shared cache object.
Returns:
A cache instance object. On error, return null.
API Stability:
Evolving.
See Also:
mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC void,* void* mprDestroyCache (MprCache *cache)

Destroy a new cache object.

Parameters:
cacheThe cache instance object returned from mprCreateCache
API Stability:
Evolving.
See Also:
mprCreateCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC int int mprExpireCacheItem (MprCache *cache, cchar *key, MprTicks expires)

Set the expiry date for a cache item.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key.
expiresTime when the cache item will expire. If expires is zero, the item is immediately removed from the cache.
Returns:
Zero if the expiry is successfully updated. Return MPR_ERR_CANT_FIND if the cache item is not present in the cache.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC void void mprGetCacheStats (MprCache *cache, int *numKeys, ssize *mem)

Get the Cache statistics.

Parameters:
cacheThe cache instance object returned from mprCreateCache
numKeysNumber of keys currently stored.
memMemory in use to store keys.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC int64 int64 mprIncCache (MprCache *cache, cchar *key, int64 amount)

Increment a numeric cache item.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key.
amountNumeric amount to increment the cache item. This may be a negative number to decrement the item.
Returns:
The new value for the cache item after incrementing.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC char,* char* mprLookupCache (MprCache *cache, cchar *key, MprTime *modified, int64 *version)

Lookup an item in the cache.

Description:
Same as mprReadCache but will not update the last accessed time.
Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key.
modifiedOptional MprTime value reference to receive the last modified time of the cache item. Set to null if not required.
versionOptional int64 value reference to receive the version number of the cache item. Set to null if not required. Cache items have a version number that is incremented every time the item is updated.
Returns:
The cache item value.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC void void mprPruneCache (MprCache *cache)

Prune the cache.

Description:
Prune the cache and discard all cached items.
Parameters:
cacheThe cache instance object returned from mprCreateCache
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC char,* char* mprReadCache (MprCache *cache, cchar *key, MprTime *modified, int64 *version)

Read an item from the cache.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key.
modifiedOptional MprTime value reference to receive the last modified time of the cache item. Set to null if not required.
versionOptional int64 value reference to receive the version number of the cache item. Set to null if not required. Cache items have a version number that is incremented every time the item is updated.
Returns:
The cache item value.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC bool bool mprRemoveCache (MprCache *cache, cchar *key)

Remove items from the cache.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key. If set to null, then remove all keys from the cache.
Returns:
True if the cache item was removed.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprSetCacheLimits, mprWriteCache
PUBLIC void void mprSetCacheLimits (MprCache *cache, int64 keys, MprTicks lifespan, int64 memory, int resolution)

Set the cache resource limits.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keysSet the maximum number of keys the cache can store.
lifespanSet the default lifespan for cache items in milliseconds.
memoryMemory limit in bytes for all cache keys and items.
resolutionSet the cache item pruner resolution. This defines how frequently the cache manager will check items for expiration.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprWriteCache
PUBLIC int int mprSetCacheLink (MprCache *cache, cchar *key, void *link)

Set a linked managed memory reference for a cached item.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key to write.
linkManaged memory reference. May be NULL.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC void void mprSetCacheNotify (MprCache *cache, MprCacheProc notify)

Set a notification callback to be invoked for events of interest on cached items.

WARNING: the callback may happen on any thread. Use careful locking to synchronize access to data. Take care not to block the thread issuing the callback
Parameters:
cacheThe cache instance object returned from mprCreateCache
notifyMprCacheProc notification callback. Invoked for events of interest on cache items. The event is set to MPR_CACHE_NOTIFY_REMOVE when items are removed from the cache. Invoked as:.
(*MprCacheProc)(MprCache *cache, cchar *key, cchar *data, int event);
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits, mprWriteCache
PUBLIC ssize ssize mprWriteCache (MprCache *cache, cchar *key, cchar *value, MprTime modified, MprTicks lifespan, int64 version, int options)

Write a cache item.

Parameters:
cacheThe cache instance object returned from mprCreateCache
keyCache item key to write.
valueValue to set for the cache item. This must be allocated memory.
modifiedValue to set for the cache last modified time. If set to zero, the current time is obtained via mprGetTime
lifespanLifespan of the item in milliseconds. The item will be removed from the cache by the Cache manager when the lifetime expires unless it is rewritten to extend the lifespan.
versionExpected version number of the item. This is used to do transactional writes to the cache item. First the version number is retrieved via mprReadCache and that version number is supplied to mprWriteCache when the item is updated. If another caller updates the item in between the read/write, the version number will not match when the item is subsequently written and this call will fail with the MPR_ERR_BAD_STATE return code. Set to zero if version checking is not required.
optionsOptions to control how the item value is updated. Use MPR_CACHE_SET to update the cache item and create if it does not exist. Use MPR_CACHE_ADD to add the item only if it does not already exits. Use MPR_CACHE_APPEND to append the parameter value to any existing cache item value. Use MPR_CACHE_PREPEND to prepend the value.
Returns:
If writing the cache item was successful this call returns the number of bytes written. Otherwise a negative MPR error code is returned. MPR_ERR_BAD_STATE will be returned if an invalid version number is supplied. MPR_ERR_ALREADY_EXISTS will be returned if MPR_CACHE_ADD is specified and the cache item already exists.
API Stability:
Evolving.
See Also:
mprCreateCache, mprDestroyCache, mprIncCache, mprReadCache, mprRemoveCache, mprSetCacheLimits

MprCmd

MprCmd

Command execution Service.

Description:
The MprCmd service enables execution of local commands. It uses three full-duplex pipes to communicate read, write and error data with the command.
API Stability:
Stable.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock
API Stability:
Internal.
Fields:
intargc Count of args in argv.
cchar **argv List of args. Null terminated.
MprCmdProccallback Handler for client output and completion.
void *callbackData Managed callback data reference.
boolcomplete All channels EOF and status gathered.
cchar **defaultEnv Environment to use if no env passed to mprStartCmd.
char *dir Current working dir for the process.
MprDispatcher *dispatcher Dispatcher to use for wait events.
MprList *env List of environment variables. Null terminated.
inteofCount Count of end-of-files.
MprCmdFilefiles[MPR_CMD_MAX_PIPE] Stdin, stdout for the command.
intflags Control flags (userFlags not here).
MprForkCallbackforkCallback Forked client callback.
void *forkData Managed fork callback data reference.
cchar **makeArgv Allocated argv.
MprMutex *mutex Multithread sync.
intoriginalPid Persistent copy of the pid.
intpid Process ID of the created process.
cchar *program Program path name.
intrequiredEof Number of EOFs required for an exit.
char *searchPath Search path to use to locate the command.
MprSignal *signal Signal handler for SIGCHLD.
intstatus Command exit status.
MprBuf *stderrBuf Standard error output from the client.
MprBuf *stdoutBuf Standard output from the client.
boolstopped Command stopped.
inttimedout Request has timedout.
void *userData User data storage.
intuserFlags User flags storage.
PUBLIC bool bool mprAreCmdEventsEnabled (MprCmd *cmd, int channel)

Return true if command events are enabled.

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
Returns:
True if I/O events are enabled for the given channel.
API Stability:
Internal.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock
PUBLIC void void mprCloseCmdFd (MprCmd *cmd, int channel)

Close the command channel.

Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
API Stability:
Stable.
See Also:
mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock
PUBLIC MprCmd,* MprCmd* mprCreateCmd (MprDispatcher *dispatcher)
PUBLIC void void mprDestroyCmd (MprCmd *cmd)
PUBLIC void void mprDisableCmdEvents (MprCmd *cmd, int channel)

Disable command I/O events.

This disables events on a given channel
Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
API Stability:
Stable.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisconnectCmd, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock
PUBLIC void void mprDisconnectCmd (MprCmd *cmd)

Disconnect a command its underlying I/O channels.

This is used to prevent further I/O wait events while still preserving the MprCmd object
Parameters:
cmdMprCmd object created via mprCreateCmd.
API Stability:
Stable.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprEnableCmdEvents, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir, mprSetCmdEnv, mprSetCmdSearchPath, mprStartCmd, mprStopCmd, mprWaitForCmd, mprWriteCmd, mprWriteCmdBlock
PUBLIC void void mprEnableCmdEvents (MprCmd *cmd, int channel)

Enable command I/O events.

This enables events on a given channel
Parameters:
cmdMprCmd object created via mprCreateCmd.
channelChannel number to close. Should be either MPR_CMD_STDIN, MPR_CMD_STDOUT or MPR_CMD_STDERR.
API Stability:
Stable.
See Also:
mprCloseCmdFd, mprCreateCmd, mprDestroyCmd, mprDisableCmdEvents, mprDisconnectCmd, mprFinalizeCmd, mprGetCmdBuf, mprGetCmdExitStatus, mprGetCmdFd, mprIsCmdComplete, mprIsCmdRunning, mprReadCmd, mprReapCmd, mprRunCmd, mprRunCmdV, mprSetCmdCallback, mprSetCmdDir,