VirtualBox

source: vbox/trunk/include/iprt/strcache.h@ 22509

Last change on this file since 22509 was 20374, checked in by vboxsync, 16 years ago

*: s/RT_\(BEGIN|END\)_DECLS/RT_C_DECLS_\1/g

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 3.9 KB
Line 
1/* $Id: strcache.h 20374 2009-06-08 00:43:21Z vboxsync $ */
2/** @file
3 * IPRT - String Cache, stub implementation.
4 */
5
6/*
7 * Copyright (C) 2009 Sun Microsystems, Inc.
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 *
26 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
27 * Clara, CA 95054 USA or visit http://www.sun.com if you need
28 * additional information or have any questions.
29 */
30
31#ifndef ___iprt_strcache_h
32#define ___iprt_strcache_h
33
34#include <iprt/types.h>
35
36RT_C_DECLS_BEGIN
37
38
39/**
40 * Create a new string cache.
41 *
42 * @returns IPRT status code
43 *
44 * @param phStrCache Where to return the string cache handle.
45 * @param pszName The name of the cache (for debug purposes).
46 */
47RTDECL(int) RTStrCacheCreate(PRTSTRCACHE phStrCache, const char *pszName);
48
49
50/**
51 * Destroys a string cache.
52 *
53 * This will cause all strings in the cache to be released and thus become
54 * invalid.
55 *
56 * @returns IPRT status.
57 *
58 * @param hStrCache Handle to the string cache. The nil and default
59 * handles are ignored quietly (VINF_SUCCESS).
60 */
61RTDECL(int) RTStrCacheDestroy(RTSTRCACHE hStrCache);
62
63
64/**
65 * Enters a string into the cache.
66 *
67 * @returns Pointer to a read-only copy of the string.
68 *
69 * @param hStrCache Handle to the string cache.
70 * @param pchString Pointer to a string. This does not need to be
71 * zero terminated, but must not contain any zero
72 * characters.
73 * @param cchString The number of characters (bytes) to enter.
74 *
75 * @remarks It is implementation dependent whether the returned string pointer
76 * differs when entering the same string twice.
77 */
78RTDECL(const char *) RTStrCacheEnterN(RTSTRCACHE hStrCache, const char *pchString, size_t cchString);
79
80/**
81 * Enters a string into the cache.
82 *
83 * @returns Pointer to a read-only copy of the string.
84 *
85 * @param hStrCache Handle to the string cache.
86 * @param psz Pointer to a zero terminated string.
87 *
88 * @remarks See RTStrCacheEnterN.
89 */
90RTDECL(const char *) RTStrCacheEnter(RTSTRCACHE hStrCache, const char *psz);
91
92
93/**
94 * Retains a reference to a string.
95 *
96 * @returns The new reference count. UINT32_MAX is returned if the string
97 * pointer is invalid.
98 */
99RTDECL(uint32_t) RTStrCacheRetain(const char *psz);
100
101/**
102 * Releases a reference to a string.
103 *
104 * @returns The new reference count.
105 * UINT32_MAX is returned if the string pointer is invalid.
106 *
107 * @param hStrCache Handle to the string cache. Passing NIL is ok,
108 * but this may come a performance hit.
109 * @param psz Pointer to a cached string.
110 */
111RTDECL(uint32_t) RTStrCacheRelease(RTSTRCACHE hStrCache, const char *psz);
112
113/**
114 * Gets the string length of a cache entry.
115 *
116 * @returns The string length. 0 if the string is invalid (asserted).
117 *
118 * @param psz Pointer to a cached string.
119 */
120RTDECL(size_t) RTStrCacheLength(const char *psz);
121
122RT_C_DECLS_END
123
124#endif
125
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette