Implementing ParserAutoInstallInfo

Network Monitor uses the ParserAutoInstallInfo export function to install a parser. When ParserAutoInstallInfo is called, the parser returns a PF_PARSERDLLINFO structure containing all the information that Network Monitor needs to install a parser DLL.

Note  Network Monitor keeps a list of existing parsers in the Parser.ini file, and creates a separate INI file for each installed parser.

During the installation process, the parser DLL must identify the following:

• The number of parsers in the DLL—including a name and comment description for each parser.
• The protocols that precede the parser protocol.
• The protocols that follow the parser protocol.

Note  Network Monitor uses the preceding and following parser protocol information to update the handoff sets and follow sets of parsers that your parser DLL identifies.

The following procedure identifies the steps necessary to implement ParserAutoInstallInfo.

To implement ParserAutoInstallInfo

1. Allocate a PF_PARSERDLLINFO structure using HeapAlloc.

2. Return memory to the heap using HeapFree.

3. Be aware that this call must also allocate a PF_PARSERINFO structure for each parser in the DLL.

4. Specify the number of parsers (typically one) that the DLL contains in the nParsers member of PF_PARSERDLLINFO.

5. Specify a name, comment, and optional Help file in the szProtocolName, szComment, and szHelpFile members of each PF_PARSERINFO structure.

6. Specify the protocols that precede each DLL protocol. One of the following conditions applies to an incoming handoff set.

   • If the preceding protocols can determine that your protocol follows from data in the preceding protocols, set the pWhoHandsOffToMe member of PF_PARSERINFO. In this case, your protocol is then added to the handoff sets of the preceding protocols.
   • If the preceding protocols cannot determine that your protocol follows from data in the preceding protocols, set pWhoCanPrecedeMe member of PF_PARSERINFO. In this case, the your protocol is then added to the follow sets of the protocols.

7. Specify the protocols that follow each DLL protocol. One of the following conditions applies to an outgoing follow-set.

   • If your protocol can determine which protocols follow based on data in your protocol, set the pWhoDoIHandOffTo member of PF_PARSERINFO. In this case, the these protocols are added to the handoff set of your protocols.
   • If your protocol cannot determine which protocols follow based on data in your protocol, set the pWhoCanFollowMe member of PF_PARSERINFO. In this case, these protocols are added to the follow set of your protocol.

8. Return the PF_PARSERDLLINFO structure to Network Monitor.

The following code example identifies a basic implementation of ParserAutoInstallInfo. The code example is taken from the generic parser that Network Monitor provides.

PPF_PARSERDLLINFO WINAPI ParserAutoInstallInfo() 
{

  /////////////////////////////////////////////////////////////////
  //
  // Allocate memory for PF_PARSERDLLINFO structure.
  //
  /////////////////////////////////////////////////////////////////
  PPF_PARSERDLLINFO pParserDllInfo; 
  PPF_PARSERINFO    pParserInfo;
  DWORD NumProtocols;
        DWORD NumParsers;
        DWORD NumFollows;
  NumParsers = 1;
  
  pParserDllInfo = (PPF_PARSERDLLINFO)HeapAlloc( GetProcessHeap(),
                                                 HEAP_ZERO_MEMORY,
                                                 sizeof( PF_PARSERDLLINFO ) +
                                                 NumParsers * sizeof( PF_PARSERINFO) );
  if( pParserDllInfo == NULL)
  {
    return NULL;
  }
  

    
  /////////////////////////////////////////////////////////////////
  //
  // Specify the number of parsers in the DLL.
  //
  /////////////////////////////////////////////////////////////////
  
  pParserDllInfo->nParsers = NumParsers;
  

  /////////////////////////////////////////////////////////////////
  // 
  // Specify the name, comment, and Help file for each protocol.
  // 
  /////////////////////////////////////////////////////////////////
  pParserInfo = &(pParserDllInfo->ParserInfo[0]);
  wsprintf( pParserInfo->szProtocolName, "TestProtocol" );
  wsprintf( pParserInfo->szComment,      "Test protocol for SDK" );
  wsprintf( pParserInfo->szHelpFile,     "");
  

  
  /////////////////////////////////////////////////////////////////
  //
  // Specify preceding protocols.
  //
  /////////////////////////////////////////////////////////////////
  PPF_HANDOFFSET    pHandoffSet;
  PPF_HANDOFFENTRY  pHandoffEntry;
  
  // Allocate PF_HANDOFFSET structure.
  NumHandoffs = 1;                   
  pHandoffSet = (PPF_HANDOFFSET)HeapAlloc( GetProcessHeap(),
                                           HEAP_ZERO_MEMORY,
                                           sizeof( PF_HANDOFFSET ) +
                                           NumHandoffs * sizeof( PF_HANDOFFENTRY) );
  if( pHandoffSet == NULL )
  {
     return pParserDllInfo;
  }

  // Fill in handoff set
  pParserInfo->pWhoHandsOffToMe = pHandoffSet;
  pHandoffSet->nEntries = NumHandoffs;

  // TCP PORT FFFF
  pHandoffEntry = &(pHandoffSet->Entry[0]);
  wsprintf( pHandoffEntry->szIniFile,    "TCPIP.INI" );
  wsprintf( pHandoffEntry->szIniSection, "TCP_HandoffSet" );
  wsprintf( pHandoffEntry->szProtocol,   "BLRPLATE" );
  pHandoffEntry->dwHandOffValue =        0xFFFF;
  pHandoffEntry->ValueFormatBase =       HANDOFF_VALUE_FORMAT_BASE_DECIMAL;    
  
  

  /////////////////////////////////////////////////////////////////
  //
  // Specify the following protocols.
  //
  /////////////////////////////////////////////////////////////////
  PPF_FOLLOWSET     pFollowSet;
  PPF_FOLLOWENTRY   pFollowEntry;
 
  // Allocate PF_FOLLOWSET structure
  NumFollows = 1;
  pFollowSet = (PPF_FOLLOWSET)HeapAlloc( GetProcessHeap(),
                                         HEAP_ZERO_MEMORY,
                                         sizeof( PF_FOLLOWSET ) +
                                         NumFollows * sizeof( PF_FOLLOWENTRY) );
  if( pFollowSet == NULL )
  {
    return pParserDllInfo;
  }

  // Fill in the follow set
  pParserInfo->pWhoCanFollowMe = pFollowSet;
  pFollowSet->nEntries = NumFollows;

  // Add SMB
  pFollowEntry = &(pFollowSet->Entry[0]);
  wsprintf( pFollowEntry->szProtocol,   "SMB" );
  


  /////////////////////////////////////////////////////////////////
  //
  // Return the PF_PARSERDLLINFO structure.
  //
  /////////////////////////////////////////////////////////////////
  return pParserDllInfo;

}