Home

Traffic Server Software Developers Kit

Writing Handler Functions

The handler function is the key component of a continuation. It is supposed to examine the event and event data, and then do something appropriate. The probable action might be to schedule another event for the continuation to received, to open up a connection to a server, or simply to destroy itself.

The continuation’s handler function is a function of type INKEventFunc. Its arguments are a continuation, an event, and a pointer to some data (this data is passed to the continuation by the caller - do not confuse this data with the continuation’s own data, associated by INKContDataSet). When the continuation is called back, the continuation and an event are passed to the handler function. The continuation is a handle to the same continuation that is invoked. The handler function typically has a switch statement to handle the events it receives:

static int some_handler (INKcont contp, INKEvent event, void *edata)
{
    .....
   switch(event) {
       case INK_EVENT_SOME_EVENT_1:
          do_some_thing_1;
          return;
      case INK_EVENT_SOME_EVENT_2:
         do_some_thing_2;
         return;
     case INK_EVENT_SOME_EVENT_3:
         do_some_thing_3;
         return;
     default: break;
     }
   return 0;
}
[Caution] Caution

You might notice that a continuation cannot determine if more events are “in flight” toward it. Do not use INKContDestroy to delete a continuation before you make sure that all incoming events, such as those sent because of INKHttpTxnHookAdd, have been handled.

The following table lists events and the corresponding type of void * data passed to handler functions:

Event Hook or API Function That Sends the Event void * Data Type
INK_EVENT_HTTP_READ_REQUEST_HDR INK_HTTP_READ_REQUEST_HDR_HOOK INKHttpTxn
INK_EVENT_HTTP_OS_DNS INK_HTTP_OS_DNS_HOOK INKHttpTxn
INK_EVENT_HTTP_SEND_REQUEST_HDR INK_HTTP_SEND_REQUEST_HDR_HOOK INKHttpTxn
INK_EVENT_HTTP_READ_CACHE_HDR INK_HTTP_READ_CACHE_HDR_HOOK INKHttpTxn
INK_EVENT_HTTP_READ_RESPONSE_HDR INK_HTTP_READ_RESPONSE_HDR_HOOK INKHttpTxn
INK_EVENT_HTTP_SEND_RESPONSE_HDR INK_HTTP_SEND_RESPONSE_HDR_HOOK INKHttpTxn
INK_EVENT_HTTP_SELECT_ALT INK_HTTP_SELECT_ALT_HOOK INKHttpTxn
INK_EVENT_HTTP_TXN_START INK_HTTP_TXN_START_HOOK INKHttpTxn
INK_EVENT_HTTP_TXN_CLOSE INK_HTTP_TXN_CLOSE_HOOK INKHttpTxn
INK_EVENT_HTTP_SSN_START INK_HTTP_SSN_START_HOOK INKHttpSsn
INK_EVENT_HTTP_SSN_CLOSE INK_HTTP_SSN_CLOSE_HOOK INKHttpSsn
     
INK_EVENT_NONE    
INK_EVENT_CACHE_LOOKUP_COMPLETE INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK INKHttpTxn
INK_EVENT_IMMEDIATE INKVConnClose, INKVIOReenable, INKContSchedule  
INK_EVENT_IMMEDIATE INK_HTTP_REQUEST_TRANSFORM_HOOK  
INK_EVENT_IMMEDIATE INK_HTTP_RESPONSE_TRANSFORM_HOOK  
INK_EVENT_CACHE_OPEN_READ INKCacheRead Cache VC
INK_EVENT_CACHE_OPEN_READ_FAILED INKCacheRead Error code, see INK_CACHE_ERROR_XXX
INK_EVENT_CACHE_OPEN_WRITE INKCacheWrite Cache VC
INK_EVENT_CACHE_OPEN_WRITE_FAILED INKCacheWrite Error code, see INK_CACHE_ERROR_XXX
INK_EVENT_CACHE_REMOVE INKCacheRemove Nothing
INK_EVENT_CACHE_REMOVE_FAILED INKCacheRemove Error code, see INK_CACHE_ERROR_XXX
INK_EVENT_NET_ACCEPT INKNetAccept, INKHttpTxnServerIntercept, INKHttpTxnIntercept Net VConnection
INK_EVENT_NET_ACCEPT_FAILED INKNetAccept, INKHttpTxnServerIntercept, INKHttpTxnIntercept Nothing
INK_EVENT_HOST_LOOKUP INKHostLookup Null pointer - error Non null pointer - INKHostLookupResult
INK_EVENT_TIMEOUT INKContSchedule  
INK_EVENT_ERROR    
     
INK_EVENT_VCONN_READ_READY INKVConnRead INKVConn
INK_EVENT_VCONN_WRITE_READY INKVConnWrite INKVConn
INK_EVENT_VCONN_READ_COMPLETE INKVConnRead INKVConn
INK_EVENT_VCONN_WRITE_COMPLETE INKVConnWrite INKVConn
INK_EVENT_VCONN_EOS INKVConnRead INKVConn
INK_EVENT_NET_CONNECT INKNetConnect INKVConn
INK_EVENT_NET_CONNECT_FAILED INKNetConnect INKVConn
     
INK_EVENT_HTTP_CONTINUE    
INK_EVENT_HTTP_ERROR    
INK_EVENT_MGMT_UPDATE INKMgmtUpdateRegister NULL

The continuation functions are listed below: