How OpenHoldem calls DLL functions

The OpenHoldem to DLL interface is small and clean. OpenHoldem will send or request information from the DLL when needed, and it is up to the DLL’s author to process these requests. The exported library function process_message is used for this interface and has the following prototype:

USERDLL_API double process_message (const char* pmessage, const void* param)

The various messages that can be passed in the “pmessage” parameter are as follows:

pmessage	meaning and parameters
state	Each scrape cycle, OpenHoldem will send the current game state to the DLL. As the author of the DLL, you will decide what to do with this game state information. The game state information is stored in a structure within OpenHoldem, and a pointer to this structure is passed to your User DLL in the “param” parameter. An example of how to cast this void pointer to the game state structure is provided in the Reference User DLL source code. The details of what is included in this game state structure are in the header file in the Reference User DLL source code.
query	Any symbol that begins with the characters “dll$” is interpreted by the OpenHoldem parser as requiring a call to the loaded User DLL in order to determine its value. The “query” message is the mechanism for requesting the value of this symbol. Any symbol name can be created for use by your User DLL, as long as it begins with “dll$”, and your DLL code knows how to handle it. So, for example, if the OpenHoldem decision engine encounters a symbol called “dll$kill_phil” in the evaluation of the “f$alli” function, then a synchronous call will be made to the User DLL to provide the value of dll$kill_phil in order to complete the evaluation of f$alli. The evaluation of f$alli will block until your DLL handles this request and provides a result. The name of the symbol (in this case, “dll$kill_phil”) is provided in the “param” parameter, and should be cast to a (const char*). A simple example of how to process this message is provided in the Reference User DLL source code.
pfgws	Immediately after your User DLL is loaded, OpenHoldem will send a “pfgws” message once, which contains a pointer to a function within OpenHoldem that allows you to retrieve OpenHoldem symbols for use in your DLL code. “pfgws” is an acronym for “Pointer to Function for Get Winholdem Symbol”. This has not been renamed to something different for legacy compatibility reasons. The pointer to the OpenHoldem “get symbol” function is provided in the “param” parameter, and should be cast to the p_getsym_t typedef and stored in a variable provided by your DLL. From then on, any time your DLL needs to know the value of one of the OpenHoldem calculated symbols, call this function. The Reference User DLL source code provides a function that shows how to use the parameter provided in this message. The prototype for this function is:   double getsym(int chair, const char* name, bool& iserr)   This sample function takes the chair and the symbol name as input parameters and returns an error code in the “iserr” output parameter. An error will be returned if, for example, the “name” parameter contains an invalid OpenHoldem symbol name.
event	There are two event messages that are passed to your DLL. Both of these messages have NULL “param” parameters. - “load” – this message is sent once immediately after your DLL is loaded. Typically this is used for some kind of initialization activity by your DLL. - “unload” – this message is sent once just prior to OpenHoldem unloading your DLL from memory. This could be due to OpenHoldem shutdown, manual intervention from the DLL menu, or new formula loading. Typically this is used to clean up your DLL’s activities, such as connections to databases, closure of threads, etc.
phl1k	This message provides a pointer to OpenHoldem’s internal hand list array, for your DLL to read and modify as needed. The “param” parameter contains a pointer to this array and should be cast to the following type:   bool inlist[1000][13][13]   OpenHoldem can store 1000 different hand lists, and the first dimension of this array specifies the hand list number, the second and third dimensions specify the rank of the first and second card, where rank0>=rank1 is interpreted to mean suited cards, and rank0<rank1 is interpreted to mean unsuited cards. This is a very sparsely populated array, where the intersection of the three dimensions specifies if the particular card pair is present in the hand list or not. A non-zero value at this intersection indicates that the card pair is present; zero indicates that the card pari is not present.
prw1326	This message provides a pointer to a prw1326 structure stored in OpenHoldem. This prw1326 structure is used to describe the manner in which OpenHoldem calculates its prwin, prtie and prlos symbols, based on the information which the DLL developer places in this structure. Unless the DLL code sets a specific enabling flag in this structure, the current prwin, prtie and prlos calculation is unchanged. Please see the {prw1326} section for more information.
p_send_chat_message	This message provides a pointer to a SendChatMessage function in OpenHoldem that allows you to send any chat message you want at any time. The OH-Script only version of f$chat only allows certain pre-defined chat messages to be sent. This message is sent once immediately after your DLL is loaded, with the pointer to the SendChatMessage function in the “Param” parameter. This parameter should be cast to the following prototype:   void SendChatMessage(char* new_message)   Usage of this function is specified in more detail in the {f$chat} section.

The order that these messages are passed after the DLL is loaded is as follows:

§ event / load

§ pfgws

§ phl1k

§ prw1326

§ p_send_chat_message

Note: Basic code examples for handling most of these DLL messages are provided in the Reference User DLL source code.

A Simple Example

An easy way to get started is to override all OH-Script processing with DLL functions. There are a number of reasons to do this, including:

- Limitations of the OH-Script language (no assignments is the biggest limitation)

- Speed of compiled code versus interpreted code

- Low level integration with other technologies (your own tracking database, for example)

To override all OH-Script processing, simply instruct each primary function to only have a call to a “dll$” symbol. For example, in f$alli, use the following code:

dll$alli

In f$rais, use the following code:

dll$rais

And so on. In your User DLL, handle each of these “dll$” symbols as described above. Now all of the decision logic has been moved from OH-Script code to code that you provide in your DLL. It is important to remember that even if you want to code up most of your bot logic in C/C++, you still must use the OpenHoldem primary functions themselves to call this logic.

Дата добавления: 2015-07-20