NAME
netsnmpcachehandler - Maintains a cache of data for use by lower
level handlers. FFuunnccttiioonnss netsnmpcache * nneettssnnmmppccaacchheeggeetthheeaadd (void) get cache head netsnmpcache * nneettssnnmmppccaacchheeffiinnddbbyyooiidd (oid *rootoid, int rootoidlen) find existing cache netsnmpcache * nneettssnnmmppccaacchheeccrreeaattee (int timeout, NetsnmpCacheLoad *loadhook, NetsnmpCacheFree *freehook, oid *rootoid, int rootoidlen) returns a cache unsigned int nneettssnnmmppccaacchheettiimmeerrssttaarrtt (netsnmpcache *cache) starts the recurring cacheload callback void nneettssnnmmppccaacchheettiimmeerrssttoopp (netsnmpcache *cache) stops the recurring cacheload callback nneettssnnmmppmmiibbhhaannddlleerr * nneettssnnmmppccaacchheehhaannddlleerrggeett (netsnmpcache *cache) returns a cache handler that can be injected into a given handler chain. nneettssnnmmppmmiibbhhaannddlleerr * nneettssnnmmppggeettccaacchheehhaannddlleerr (int timeout, NetsnmpCacheLoad *loadhook, NetsnmpCacheFree *freehook, oid *rootoid, int rootoidlen) returns a cache handler that can be injected into a given handler chain. int nneettssnnmmppccaacchheehhaannddlleerrrreeggiisstteerr (nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn *reginfo, netsnmpcache *cache) functionally the same as calling nneettssnnmmpprreeggiisstteerrhhaannddlleerr(()) but also injects a cache handler at the same time for you. int nneettssnnmmpprreeggiisstteerrccaacchheehhaannddlleerr (nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn *reginfo, int timeout, NetsnmpCacheLoad *loadhook, NetsnmpCacheFree *freehook) functionally the same as calling nneettssnnmmpprreeggiisstteerrhhaannddlleerr(()) but also injects a cache handler at the same time for you. NETSNMPSTATICINLINE char * bbuuiillddccaacchheennaammee (const char *name) void nneettssnnmmppccaacchheerreeqqiinnffooiinnsseerrtt (netsnmpcache *cache, nneettssnnmmppaaggeennttrreeqquueessttiinnffoo *reqinfo, const char *name) Insert the cache information for a given request (PDU). netsnmpcache * nneettssnnmmppccaacchheerreeqqiinnffooeexxttrraacctt (nneettssnnmmppaaggeennttrreeqquueessttiinnffoo *reqinfo, const char *name) Extract the cache information for a given request (PDU). netsnmpcache * nneettssnnmmppeexxttrraaccttccaacchheeiinnffoo (nneettssnnmmppaaggeennttrreeqquueessttiinnffoo *reqinfo) Extract the cache information for a given request (PDU). int nneettssnnmmppccaacchheecchheecckkeexxppiirreedd (netsnmpcache *cache) Check if the cache timeout has passed. int nneettssnnmmppccaacchheecchheecckkaannddrreellooaadd (netsnmpcache *cache) Reload the cache if required. int nneettssnnmmppccaacchheeiissvvaalliidd (nneettssnnmmppaaggeennttrreeqquueessttiinnffoo *reqinfo, const char *name) Is the cache valid for a given request? int nneettssnnmmppiissccaacchheevvaalliidd (nneettssnnmmppaaggeennttrreeqquueessttiinnffoo *reqinfo) for backwards compat int nneettssnnmmppccaacchheehheellppeerrhhaannddlleerr (nneettssnnmmppmmiibbhhaannddlleerr *handler, nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn *reginfo, nneettssnnmmppaaggeennttrreeqquueessttiinnffoo *reqinfo, nneettssnnmmpprreeqquueessttiinnffoo *requests) Implements the cache handler. void rreelleeaasseeccaacchheeddrreessoouurrcceess (unsigned int regNo, void *clientargs) run regularly to automatically release cached resources. DDeettaaiilleedd DDeessccrriippttiioonn This helper checks to see whether the data has been loaded 'recently' (according to the timeout for that particular cache) and calls the registered 'loadcache' routine if necessary. The lower handlers can then work with this local cached data.A timeout value of -1 will cause nneettssnnmmppccaacchheecchheecckkeexxppiirreedd(()) to
always return true, and thus the cache will be reloaded for every request. To minimze resource use by the agent, a periodic callback checks for expired caches, and will call the freecache function for any expired cache. The loadcache route should return a negative number if the cache was not successfully loaded. 0 or any positive number indicates successs. Several flags can be set to affect the operations on the cache. If NETSNMPCACHEDONTINVALIDATEONSET is set, the freecache method will not be called after a set request has processed. It is assumed that the lower mib handler using the cache has maintained cache consistency. If NETSNMPCACHEDONTFREEBEFORELOAD is set, the freecache method will not be called before the loadcache method is called. It is assumed that the loadcache routine will properly deal with being called with a valid cache. If NETSNMPCACHEDONTFREEEXPIRED is set, the freecache method will not be called with the cache expires. The expired flag will be set, but the valid flag will not be cleared. It is assumed that the loadcache routine will properly deal with being called with a valid cache. If NETSNMPCACHEPRELOAD is set when a the cache handler is created, the cache load routine will be called immediately. If NETSNMPCACHEDONTAUTORELEASE is set, the periodic callback that checks for expired caches will skip the cache. The cache will only be checked for expiration when a request triggers the cache handler. This is useful if the cache has it's own periodic callback to keep the cache fresh. If NETSNMPCACHEAUTORELOAD is set, a timer will be set up to reload the cache when it expires. This is useful for keeping the cache fresh, even in the absence of incoming snmp requests. Here are some suggestions for some common situations. Cached File: If your table is based on a file that may periodically change, you can test the modification date to see if the file has changed since the last cache load. To get the cache helper to call theload function for every request, set the timeout to -1, which will
cause the cache to always report that it is expired. This means that you will want to prevent the agent from flushing the cache when it has expired, and you will have to flush it manually if you detect that the file has changed. To accomplish this, set the following flags: NETSNMPCACHEDONTFREEEXPIRED NETSNMPCACHEDONTAUTORELEASE Constant (periodic) reload: If you want the cache kept up to date regularly, even if no requests for the table are received, you can have your cache load routine called periodically. This is very useful if you need to monitor the data for changes (eg a LastChanged object). You will need to prevent the agent from flushing the cache when it expires. Set the cache timeout to the frequency, in seconds, that you wish to reload your cache, and set the following flags: NETSNMPCACHEDONTFREEEXPIRED NETSNMPCACHEDONTAUTORELEASE NETSNMPCACHEAUTORELOAD FFuunnccttiioonn DDooccuummeennttaattiioonn iinntt nneettssnnmmppccaacchheecchheecckkaannddrreellooaadd ((nneettssnnmmppccaacchhee ** ccaacchhee)) Reload the cache if required. Definition at line 383 of file cachehandler.c. References netsnmpcachecheckexpired(). Referenced by netsnmpcachehelperhandler(). iinntt nneettssnnmmppccaacchheecchheecckkeexxppiirreedd ((nneettssnnmmppccaacchhee ** ccaacchhee)) Check if the cache timeout has passed. Sets and return the expired flag. Definition at line 368 of file cachehandler.c. References atimeready(). Referenced by netsnmpcachecheckandreload(), and releasecachedresources(). nneettssnnmmppccaacchhee** nneettssnnmmppccaacchheeccrreeaattee ((iinntt ttiimmeeoouutt,, NNeettssnnmmppCCaacchheeLLooaadd ** llooaaddhhooookk,, NNeettssnnmmppCCaacchheeFFrreeee ** ffrreeeehhooookk,, ooiidd ** rroooottooiidd,, iinntt rroooottooiiddlleenn)) returns a cache Definition at line 140 of file cachehandler.c. References snmplog(), and SNMPMALLOCTYPEDEF. Referenced by netsnmpgetcachehandler(). nneettssnnmmppccaacchhee** nneettssnnmmppccaacchheeffiinnddbbyyooiidd ((ooiidd ** rroooottooiidd,, iinntt rroooottooiiddlleenn)) find existing cache Definition at line 124 of file cachehandler.c. References netsnmpoidequals(). nneettssnnmmppccaacchhee** nneettssnnmmppccaacchheeggeetthheeaadd ((vvooiidd)) get cache head Definition at line 116 of file cachehandler.c. nneettssnnmmppmmiibbhhaannddlleerr** nneettssnnmmppccaacchheehhaannddlleerrggeett ((nneettssnnmmppccaacchhee ** ccaacchhee)) returns a cache handler that can be injected into a given handler chain. Definition at line 245 of file cachehandler.c. References netsnmpmibhandlers::flags, netsnmpmibhandlers::myvoid, netsnmpcachetimerstart(), netsnmpcreatehandler(), and netsnmpmibhandler. Referenced by netsnmpcachehandlerregister(), and netsnmpgetcachehandler(). iinntt nneettssnnmmppccaacchheehhaannddlleerrrreeggiisstteerr ((nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn ** rreeggiinnffoo,, nneettssnnmmppccaacchhee ** ccaacchhee)) functionally the same as calling nneettssnnmmpprreeggiisstteerrhhaannddlleerr(()) but also injects a cache handler at the same time for you. Definition at line 293 of file cachehandler.c. References netsnmpcachehandlerget(), netsnmpinjecthandler(), netsnmpmibhandler, and netsnmpregisterhandler(). iinntt nneettssnnmmppccaacchheehheellppeerrhhaannddlleerr ((nneettssnnmmppmmiibbhhaannddlleerr ** hhaannddlleerr,, nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn ** rreeggiinnffoo,, nneettssnnmmppaaggeennttrreeqquueessttiinnffoo ** rreeqqiinnffoo,, nneettssnnmmpprreeqquueessttiinnffoo ** rreeqquueessttss))Implements the cache handler. next handler called automatically -
'AUTONEXT'next handler called automatically - 'AUTONEXT'
next handler called automatically - 'AUTONEXT' Definition at line 418
of file cachehandler.c. References netsnmpmibhandlers::flags, netsnmphandlerregistrations::handlerName, netsnmpagentrequestinfos::mode, netsnmpmibhandlers::myvoid, netsnmpcachecheckandreload(), netsnmpcacheisvalid(), netsnmpcachereqinfoinsert(), netsnmphandlerregistration, netsnmpsetallrequestserror(), netsnmphandlerregistrations::rootoid, netsnmphandlerregistrations::rootoidlen, and snmplog(). iinntt nneettssnnmmppccaacchheeiissvvaalliidd ((nneettssnnmmppaaggeennttrreeqquueessttiinnffoo ** rreeqqiinnffoo,, ccoonnsstt cchhaarr ** nnaammee)) Is the cache valid for a given request? Definition at line 400 of file cachehandler.c. References netsnmpcachereqinfoextract(). Referenced by netsnmpcachehelperhandler(), and netsnmpiscachevalid(). nneettssnnmmppccaacchhee** nneettssnnmmppccaacchheerreeqqiinnffooeexxttrraacctt ((nneettssnnmmppaaggeennttrreeqquueessttiinnffoo ** rreeqqiinnffoo,, ccoonnsstt cchhaarr ** nnaammee)) Extract the cache information for a given request (PDU). Definition at line 348 of file cachehandler.c. References SNMPFREE. Referenced by netsnmpcacheisvalid(), and netsnmpextractcacheinfo(). vvooiidd nneettssnnmmppccaacchheerreeqqiinnffooiinnsseerrtt ((nneettssnnmmppccaacchhee ** ccaacchhee,, nneettssnnmmppaaggeennttrreeqquueessttiinnffoo ** rreeqqiinnffoo,, ccoonnsstt cchhaarr ** nnaammee)) Insert the cache information for a given request (PDU). Definition at line 331 of file cachehandler.c. References netsnmpcreatedatalist(), and SNMPFREE. Referenced by netsnmpcachehelperhandler(). uunnssiiggnneedd iinntt nneettssnnmmppccaacchheettiimmeerrssttaarrtt ((nneettssnnmmppccaacchhee ** ccaacchhee)) starts the recurring cacheload callback Definition at line 195 of file cachehandler.c. References snmpalarmregister(), and snmplog(). Referenced by netsnmpcachehandlerget(). vvooiidd nneettssnnmmppccaacchheettiimmeerrssttoopp ((nneettssnnmmppccaacchhee ** ccaacchhee)) stops the recurring cacheload callback Definition at line 225 of file cachehandler.c. References snmpalarmunregister(), and snmplog(). nneettssnnmmppccaacchhee** nneettssnnmmppeexxttrraaccttccaacchheeiinnffoo ((nneettssnnmmppaaggeennttrreeqquueessttiinnffoo ** rreeqqiinnffoo)) Extract the cache information for a given request (PDU). Definition at line 360 of file cachehandler.c. References netsnmpcachereqinfoextract(). nneettssnnmmppmmiibbhhaannddlleerr** nneettssnnmmppggeettccaacchheehhaannddlleerr ((iinntt ttiimmeeoouutt,, NNeettssnnmmppCCaacchheeLLooaadd ** llooaaddhhooookk,, NNeettssnnmmppCCaacchheeFFrreeee ** ffrreeeehhooookk,, ooiidd ** rroooottooiidd,, iinntt rroooottooiiddlleenn)) returns a cache handler that can be injected into a given handler chain. Definition at line 274 of file cachehandler.c. References netsnmpmibhandlers::myvoid, netsnmpcachecreate(), netsnmpcachehandlerget(), and netsnmpmibhandler. Referenced by netsnmpregistercachehandler(). iinntt nneettssnnmmppiissccaacchheevvaalliidd ((nneettssnnmmppaaggeennttrreeqquueessttiinnffoo ** rreeqqiinnffoo)) for backwards compat nneettssnnmmppccaacchheeiissvvaalliidd(()) is preferred. Definition at line 411 of file cachehandler.c. References netsnmpcacheisvalid(). iinntt nneettssnnmmpprreeggiisstteerrccaacchheehhaannddlleerr ((nneettssnnmmpphhaannddlleerrrreeggiissttrraattiioonn ** rreeggiinnffoo,, iinntt ttiimmeeoouutt,, NNeettssnnmmppCCaacchheeLLooaadd ** llooaaddhhooookk,, NNeettssnnmmppCCaacchheeFFrreeee ** ffrreeeehhooookk)) functionally the same as calling nneettssnnmmpprreeggiisstteerrhhaannddlleerr(()) but also injects a cache handler at the same time for you. Definition at line 306 of file cachehandler.c. References netsnmpgetcachehandler(), netsnmpinjecthandler(), netsnmpmibhandler, netsnmpregisterhandler(), netsnmphandlerregistrations::rootoid, and netsnmphandlerregistrations::rootoidlen. vvooiidd rreelleeaasseeccaacchheeddrreessoouurrcceess ((uunnssiiggnneedd iinntt rreeggNNoo,, vvooiidd ** cclliieennttaarrggss))run regularly to automatically release cached resources. xxx - method
to prevent cache from expiring while a request is being processed (e.g. delegated request). proposal: set a flag, which would be cleared when request finished (which could be acomplished by a dummy data list item in agent req info & custom free function). Definition at line 575 of file cachehandler.c. References netsnmpcachecheckexpired(), releasecachedresources(), and snmpalarmregister(). Referenced by releasecachedresources().netc-ascnhmephandler: Maintains a cache24ofJadnat2a00f5or use by lower level handlers.(3)