strcache.h revision c7814cf6e1240a519cbec0441e033d0e2470ed00
20593760b116c90f3e439552763eef632a3bbb17vboxsync * IPRT - String Cache, stub implementation.
c7814cf6e1240a519cbec0441e033d0e2470ed00vboxsync * Copyright (C) 2009-2010 Oracle Corporation
20593760b116c90f3e439552763eef632a3bbb17vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
20593760b116c90f3e439552763eef632a3bbb17vboxsync * available from http://www.virtualbox.org. This file is free software;
20593760b116c90f3e439552763eef632a3bbb17vboxsync * you can redistribute it and/or modify it under the terms of the GNU
20593760b116c90f3e439552763eef632a3bbb17vboxsync * General Public License (GPL) as published by the Free Software
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * The contents of this file may alternatively be used under the terms
20593760b116c90f3e439552763eef632a3bbb17vboxsync * of the Common Development and Distribution License Version 1.0
20593760b116c90f3e439552763eef632a3bbb17vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * VirtualBox OSE distribution, in which case the provisions of the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * CDDL are applicable instead of those of the GPL.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * You may elect to license modified versions of this file under the
20593760b116c90f3e439552763eef632a3bbb17vboxsync * terms and conditions of either the GPL or the CDDL or both.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Create a new string cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns IPRT status code
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param phStrCache Where to return the string cache handle.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pszName The name of the cache (for debug purposes).
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(int) RTStrCacheCreate(PRTSTRCACHE phStrCache, const char *pszName);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Destroys a string cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * This will cause all strings in the cache to be released and thus become
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns IPRT status.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hStrCache Handle to the string cache. The nil and default
20593760b116c90f3e439552763eef632a3bbb17vboxsync * handles are ignored quietly (VINF_SUCCESS).
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(int) RTStrCacheDestroy(RTSTRCACHE hStrCache);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Enters a string into the cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns Pointer to a read-only copy of the string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hStrCache Handle to the string cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param pchString Pointer to a string. This does not need to be
20593760b116c90f3e439552763eef632a3bbb17vboxsync * zero terminated, but must not contain any zero
20593760b116c90f3e439552763eef632a3bbb17vboxsync * characters.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param cchString The number of characters (bytes) to enter.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @remarks It is implementation dependent whether the returned string pointer
20593760b116c90f3e439552763eef632a3bbb17vboxsync * differs when entering the same string twice.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(const char *) RTStrCacheEnterN(RTSTRCACHE hStrCache, const char *pchString, size_t cchString);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Enters a string into the cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns Pointer to a read-only copy of the string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hStrCache Handle to the string cache.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param psz Pointer to a zero terminated string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @remarks See RTStrCacheEnterN.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(const char *) RTStrCacheEnter(RTSTRCACHE hStrCache, const char *psz);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Retains a reference to a string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns The new reference count. UINT32_MAX is returned if the string
20593760b116c90f3e439552763eef632a3bbb17vboxsync * pointer is invalid.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Releases a reference to a string.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns The new reference count.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * UINT32_MAX is returned if the string pointer is invalid.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param hStrCache Handle to the string cache. Passing NIL is ok,
20593760b116c90f3e439552763eef632a3bbb17vboxsync * but this may come a performance hit.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param psz Pointer to a cached string.
20593760b116c90f3e439552763eef632a3bbb17vboxsyncRTDECL(uint32_t) RTStrCacheRelease(RTSTRCACHE hStrCache, const char *psz);
20593760b116c90f3e439552763eef632a3bbb17vboxsync * Gets the string length of a cache entry.
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @returns The string length. 0 if the string is invalid (asserted).
20593760b116c90f3e439552763eef632a3bbb17vboxsync * @param psz Pointer to a cached string.