This file contains type definitions of the function pointers which the user must set to point to any rules functions which he/she has instantiated. The mapping of rules function pointers to user rules functions is done in the user's initialization function.
This initialization function (MQeRules_NewFunction) is also the function which serves as the entry point to the user's rules module. It is therefore mandatory, whereas all other rules functions are optional.
The initialization function is called when the queue manager is loaded into memory. This is when the rules module is loaded. The module is unloaded when the queue manager is freed from memory. Thus, any one rules implementation is linked to the lifecycle of a single queue manager. Only one rules module can be loaded during a queue manager's lifecycle in memory but other modules can be loaded from this module if required. The 'master rules' functions could invoke the corresponding functions in any other modules as required.
The rules initialization function is the only rules function for which the user has to provide an implementation. Where the user does not provide a function to map to one of the other rules functions, the default behaviour is documented under the relevant function prototype below.
This file also contains definitions of all of the input and output structure parameters to be used in users' implementations of rules functions.
Note in particular the MQEVOID * pPrivateData element in the input structure parameter for most rules and the output structure parameter for MQeRules_NewFunction. This element can be assigned a rules instance structure (as seen in the examples) in MQeRules_NewFunction. This structure is then carried around between user's rules functions so can be used to contain rules 'global' data.
Data Structures | |
struct | MQeRulesActivateQMgr_in_st_ |
input parameter structure for MQeRules_ActivateQMgrFunction. More... | |
struct | MQeRulesActivateQMgr_out_st_ |
output parameter structure for MQeRules_ActivateQMgrFunction. More... | |
struct | MQeRulesCloseQMgr_in_st_ |
input parameter structure for MQeRules_CloseQMgrFunction. More... | |
struct | MQeRulesCloseQMgr_out_st_ |
output parameter structure for MQeRules_CloseQMgrFunction. More... | |
struct | MQeRulesDeleteMessage_in_st_ |
input parameter structure for MQeRules_DeleteMessageFunction. More... | |
struct | MQeRulesDeleteMessage_out_st_ |
output parameter structure for MQeRules_DeleteMessageFunction. More... | |
struct | MQeRulesGetMessage_in_st_ |
input parameter structure for MQeRules_GetMessageFunction. More... | |
struct | MQeRulesGetMessage_out_st_ |
output parameter structure for MQeRules_GetMessageFunction. More... | |
struct | MQeRulesPutMessage_in_st_ |
input parameter structure for MQeRules_PutMessageFunction. More... | |
struct | MQeRulesPutMessage_out_st_ |
output parameter structure for MQeRules_PutMessageFunction. More... | |
struct | MQeRulesTransmitQueue_in_st_ |
input parameter structure for MQeRules_TransmitQueueFunction. More... | |
struct | MQeRulesTransmitQueue_out_st_ |
output parameter structure for MQeRules_TransmitQueueFunction. More... | |
struct | MQeRulesTransmitQMgr_in_st_ |
input parameter structure for MQeRules_TransmitQMgrFunction. More... | |
struct | MQeRulesTransmitQMgr_out_st_ |
output parameter structure for MQeRules_TransmitQMgrFunction. More... | |
struct | MQeRulesUndoQMgr_in_st_ |
input parameter structure for MQeRules_UndoQMgrFunction. More... | |
struct | MQeRulesUndoQMgr_out_st_ |
output parameter structure for MQeRules_UndoQMgrFunction. More... | |
struct | MQeRulesActivateQueue_in_st_ |
input parameter structure for MQeRules_ActivateQueueFunction. More... | |
struct | MQeRulesActivateQueue_out_st_ |
output parameter structure for MQeRules_ActivateQueueFunction. More... | |
struct | MQeRulesBrowseMessage_in_st_ |
input parameter structure for MQeRules_BrowseMessageFunction. More... | |
struct | MQeRulesBrowseMessage_out_st_ |
output parameter structure for MQeRules_BrowseMessageFunction. More... | |
struct | MQeRulesCloseQueue_in_st_ |
input parameter structure for MQeRules_CloseQueueFunction. More... | |
struct | MQeRulesCloseQueue_out_st_ |
output parameter structure for MQeRules_CloseQueueFunction. More... | |
struct | MQeRulesDuplicateMessage_in_st_ |
input parameter structure for MQeRules_DuplicateMessageFunction. More... | |
struct | MQeRulesDuplicateMessage_out_st_ |
output parameter structure for MQeRules_DuplicateMessageFunction. More... | |
struct | MQeRulesGotMessage_in_st_ |
input parameter structure for MQeRules_GotMessageFunction. More... | |
struct | MQeRulesGotMessage_out_st_ |
output parameter structure for MQeRules_GotMessageFunction. More... | |
struct | MQeRulesBrowsedMessage_in_st_ |
input parameter structure for MQeRules_BrowsedMessageFunction. More... | |
struct | MQeRulesBrowsedMessage_out_st_ |
output parameter structure for MQeRules_BrowsedMessageFunction. More... | |
struct | MQeRulesMessageExpired_in_st_ |
input parameter structure for MQeRules_MessageExpiredFunction. More... | |
struct | MQeRulesMessageExpired_out_st_ |
output parameter structure for MQeRules_MessageExpiredFunction. More... | |
struct | MQeRulesTransmitMessage_in_st_ |
input parameter structure for MQeRules_TransmitMessageFunction. More... | |
struct | MQeRulesTransmitMessage_out_st_ |
output parameter structure for MQeRules_TransmitMessageFunction. More... | |
struct | MQeRulesUndoQueue_in_st_ |
input parameter structure for MQeRules_UndoQueueFunction. More... | |
struct | MQeRulesUndoQueue_out_st_ |
output parameter structure for MQeRules_UndoQueueFunction. More... | |
struct | MQeRulesFree_in_st_ |
input parameter structure for MQeRules_FreeFunction. More... | |
struct | MQeRulesFree_out_st_ |
output parameter structure for MQeRules_FreeFunction. More... | |
struct | MQeRulesNew_in_st_ |
input parameter structure for MQeRules_NewFunction. More... | |
struct | MQeRulesNew_out_st_ |
output parameter structure for MQeRules_NewFunction. More... | |
Typedefs | |
typedef MQEVOID(* | MQeRules_ActivateQMgrFunction )(MQeRulesActivateQMgr_in_ *, MQeRulesActivateQMgr_out_ *) |
function pointer type signature for a rules plugin ActivateQMgr function implementation. | |
typedef MQEVOID(* | MQeRules_CloseQMgrFunction )(MQeRulesCloseQMgr_in_ *, MQeRulesCloseQMgr_out_ *) |
function pointer type signature for a rules plugin CloseQMgr function implementation. | |
typedef MQERETURN(* | MQeRules_DeleteMessageFunction )(MQeRulesDeleteMessage_in_ *, MQeRulesDeleteMessage_out_ *) |
function pointer type signature for a rules plugin DeleteMessage function implementation. | |
typedef MQERETURN(* | MQeRules_GetMessageFunction )(MQeRulesGetMessage_in_ *, MQeRulesGetMessage_out_ *) |
function pointer type signature for a rules plugin GetMessage function implementation. | |
typedef MQERETURN(* | MQeRules_PutMessageFunction )(MQeRulesPutMessage_in_ *, MQeRulesPutMessage_out_ *) |
function pointer type signature for a rules plugin PutMessage function implementation. | |
typedef MQERETURN(* | MQeRules_TransmitQueueFunction )(MQeRulesTransmitQueue_in_ *, MQeRulesTransmitQueue_out_ *) |
function pointer type signature for a rules plugin TransmitQueue function implementation. | |
typedef MQERETURN(* | MQeRules_TransmitQMgrFunction )(MQeRulesTransmitQMgr_in_ *, MQeRulesTransmitQMgr_out_ *) |
function pointer type signature for a rules plugin TransmitQMgr function implementation. | |
typedef MQEVOID(* | MQeRules_UndoQMgrFunction )(MQeRulesUndoQMgr_in_ *, MQeRulesUndoQMgr_out_ *) |
function pointer type signature for a rules plugin UndoQMgr function implementation. | |
typedef MQEVOID(* | MQeRules_ActivateQueueFunction )(MQeRulesActivateQueue_in_ *, MQeRulesActivateQueue_out_ *) |
function pointer type signature for a rules plugin ActivateQueue function implementation. | |
typedef MQERETURN(* | MQeRules_BrowseMessageFunction )(MQeRulesBrowseMessage_in_ *, MQeRulesBrowseMessage_out_ *) |
function pointer type signature for a rules plugin BrowseMessage function implementation. | |
typedef MQEVOID(* | MQeRules_CloseQueueFunction )(MQeRulesCloseQueue_in_ *, MQeRulesCloseQueue_out_ *) |
function pointer type signature for a rules plugin CloseQueue function implementation. | |
typedef MQEVOID(* | MQeRules_DuplicateMessageFunction )(MQeRulesDuplicateMessage_in_ *, MQeRulesDuplicateMessage_out_ *) |
function pointer type signature for a rules plugin DuplicateMessage function implementation. | |
typedef MQERETURN(* | MQeRules_GotMessageFunction )(MQeRulesGotMessage_in_ *, MQeRulesGotMessage_out_ *) |
function pointer type signature for a rules plugin GotMessage function implementation. | |
typedef MQERETURN(* | MQeRules_BrowsedMessageFunction )(MQeRulesBrowsedMessage_in_ *, MQeRulesBrowsedMessage_out_ *) |
function pointer type signature for a rules plugin BrowsedMessage function implementation. | |
typedef MQEVOID(* | MQeRules_MessageExpiredFunction )(MQeRulesMessageExpired_in_ *, MQeRulesMessageExpired_out_ *) |
function pointer type signature for a rules plugin MessageExpired function implementation. | |
typedef MQERETURN(* | MQeRules_TransmitMessageFunction )(MQeRulesTransmitMessage_in_ *, MQeRulesTransmitMessage_out_ *) |
function pointer type signature for a rules plugin TransmitMessage function implementation. | |
typedef MQEVOID(* | MQeRules_UndoQueueFunction )(MQeRulesUndoQueue_in_ *, MQeRulesUndoQueue_out_ *) |
function pointer type signature for a rules plugin UndoQueue function implementation. | |
typedef MQEVOID(* | MQeRules_FreeFunction )(MQeRulesFree_in_ *, MQeRulesFree_out_ *) |
function pointer type signature for a rules plugin Free function implementation. | |
typedef MQERETURN(* | MQeRules_NewFunction )(MQeRulesNew_in_ *, MQeRulesNew_out_ *) |
function pointer type signature for a rules plugin New function implementation. |
|
function pointer type signature for a rules plugin ActivateQMgr function implementation.
Points to a rule called when the queue manager is activated. The rule implementation must be mapped to fPtrActivateQMgr in the user's rules initialisation function - see MQeRules_NewFunction. It cannot prevent the queue manager being activated - it is for notification purposes only. There is no default behaviour if this rule is not implemented.
void timeToTrigger(); struct exampleRules_st_ { // rules instance structure MQeAdministratorHndl hAdmin; // administrator handle to carry around between rules functions FILE * ifp; // file handle for logging rules MQEBOOL carryOn; // used for trigger transmission thread MQEINT32 triggerInterval; // used for trigger transmission thread HANDLE hThread; // handle for the trigger transmission thread }; typedef struct exampleRules_st_ exampleRules_; .. DLLEXPORT MQERETURN MQEPUBLISHED exampleRules_activateQueueManager( MQeRulesActivateQMgr_in_ * pInput , MQeRulesActivateQMgr_out_ * pOutput) { // retrieve exception block - passed from application MQeExceptBlock * pExceptBlock = (MQeExceptBlock *)(pOutput->pExceptBlock); // retrieve private data structure passed between user's rules invocations exampleRules_ * pRulesInstance = (exampleRules_ *)(pInput->pPrivateData); MQeQueueManagerHndl hQueueManager; MQERETURN rc = MQERETURN_OK; rc = mqeQueueManager_getCurrentQueueManager(pExceptBlock, &hQueueManager); if(MQERETURN_OK == rc) { DWORD tid; //set up the private data administrator handle using the retrieved application queue manager handle rc = mqeAdministrator_new(pExceptBlock,&pRulesInstance->hAdmin,hQueueManager); // Launch thread to govern calls to trigger transmission #if MQE_PLATFORM == PLATFORM_WIN32_MVC pRulesInstance->hThread = (HANDLE) _beginthreadex(NULL, 0, timeToTrigger, (MQEVOID *)pRulesInstance, 0, &tid); if(pRulesInstance->hThread == 0) { // thread creation failed SET_EXCEPT_BLOCK(pExceptBlock, MQERETURN_RULES_ERROR, MQEREASON_NA); } #else pRulesInstance->hThread = (HANDLE) CreateThread(NULL, 0, timeToTrigger, (MQEVOID *)pRulesInstance, 0, &tid); if(pRulesInstance->hThread == NULL) { // thread creation failed SET_EXCEPT_BLOCK(pExceptBlock, MQERETURN_RULES_ERROR, MQEREASON_NA); } #endif } } MQEVOID MQEPUBLISHED timeToTrigger(MQEINT32 interval) { MQERETURN rc = MQE_RETURN_OK; MQEINT32 lastType, lastState; MQeExceptBlock exceptBlock; SET_EXCEPT_BLOCK_TO_DEFAULT(&exceptBlock); ... // retrieve the current queue manager rc = mqeQueueManager_getCurrentQueueManager(&exceptBlock, &hQueueManager); if(MQERETURN_OK == rc) { while(MQERETURN_OK == EC(&exceptBlock) && pRulesInstance->carryOn == MQE_TRUE) { // now attempt to trigger transmission rc = mqeQueueManager_triggerTransmission(hQueueManager, &exceptBlock); // wait for the duration of the trigger interval Sleep(pRulesInstance->triggerInterval); } } } |
|
function pointer type signature for a rules plugin CloseQMgr function implementation.
Points to a rule called when the queue manager is closing. The rule cannot be used to prevent the closure of the queue manager. Thus there is no default behaviour imposed if the rule is not implemented. The rule implementation must be mapped to fPtrCloseQMgr in the user's rules initialisation function.
See example for MQeRules_ActivateQMgrFunction
DLLEXPORT MQEVOID MQEPUBLISHED exampleRules_CloseQMgr( MQeRulesCloseQMgr_in_ * pInput , MQeRulesCloseQMgr_out_ * pOutput) { MQERETURN rc = MQERETURN_OK; MQeQueueManagerHndl hQueueManager; exampleRules_ * pRulesInstance = (exampleRules_ *)pInput->pPrivateData; DWORD result; MQeExceptBlock exceptBlock = *((MQeExceptBlock *)pOutput->pExceptBlock); SET_EXCEPT_BLOCK_TO_DEFAULT(&exceptBlock); // Effect the ending of the thread by setting the MQEBOOL continue to MQE_FALSE // This leads to a return from timeToTrigger() and hence the implicit call to _endthreadex pRulesInstance->carryOn = MQE_FALSE; // wait for the thread in any case result = WaitForSingleObject(pRulesInstance->hThread, INFINITE); ... // retrieve the current queue manager rc = mqeQueueManager_getCurrentQueueManager(&exceptBlock, &hQueueManager); if(MQERETURN_OK == rc) { // attempt to trigger transmission one last time to clean up queue rc = mqeQueueManager_triggerTransmission(hQueueManager, &exceptBlock); } } |
|
function pointer type signature for a rules plugin DeleteMessage function implementation.
Points to a rule called when a request is made to delete a message. The rule can prevent deletion by a return code of MQERETURN_RULES_DISALLOWED_BY_RULE. The default behaviour is to allow the operation if the rule is not implemented. The rule implementation must be mapped to fPtrDeleteMessage in the user's rules initialisation function.
MQEBOOL isEqual = MQE_FALSE; rc = mqeString_newUtf8(pExceptBlock, &hCompareString, "TopSecretQueue"); if(MQERETURN_OK == rc) { rc = mqeString_equalTo(pInput->hQueueName, pExceptBlock, &isEqual, hCompareString); if(MQERETURN_OK == rc && isEqual == MQE_TRUE) { // don't allow a message to be deleted from queue named "TopSecretQueue" SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE,MQEREASON_NA); } } |
|
function pointer type signature for a rules plugin GetMessage function implementation.
Points to a rule called when a request is made to get a message from a queue. The rule can prevent a message being got with a return code of MQERETURN_RULES_DISALLOWED_BY_RULE. The default behaviour if the rule is not implemented is to allow the operation. The rule implementation must be mapped to fPtrGetMessage in the user's rules initialisation function.
// if the destination queue manager is the local queue manager rc = mqeQueueManager_getName( hQueueManager, pExceptBlock, &hQueueManagerName); if(MQERETURN_OK == rc) { rc = mqeString_equalTo(pInput->hQueue_QueueManagerName,pExceptBlock,&isEqual,hQueueManagerName); if(MQERETURN_OK == rc && isEqual) { // if the destination queue name is "OutboundQueue" rc = mqeString_newUtf8(pExceptBlock, &hCompareString, "OutboundQueue"); rc = mqeString_equalTo(pInput->hQueueName,pExceptBlock,&isEqual,hCompareString); if(MQERETURN_OK == rc && isEqual) { // password required for this queue MQEBOOL contains = MQE_FALSE; rc = mqeString_newUtf8(pExceptBlock,&hFieldName, "password"); rc = mqeFields_contains(hFilter, pExceptBlock, &contains, hFieldName); if(MQERETURN_OK == rc && contains == MQE_FALSE) { SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE,MQEREASON_NA); } else { // parse password, etc. } } } } |
|
function pointer type signature for a rules plugin PutMessage function implementation.
Points to a rule called when a request is made to put a message onto a queue. The rule can refuse the request via a return code of MQERETURN_RULES_DISALLOWED_BY_RULE. The default behaviour is to allow the operation if the rule is not implemented. The rule implementation must be mapped to fPtrPutMessage in the user's rules initialisation function.
// Only allow msgs containing an ID field to be placed on the Queue MQEBOOL contains = MQE_FALSE; rc = mqeFields_contains(pInput->hMsg, pExceptBlock, &contains, MQE_MSG_MSGID); if(MQERETURN_OK == rc && !contains) { SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA); } |
|
function pointer type signature for a rules plugin TransmitQueue function implementation.
Points to a rule called whenever a queue manager attempts to send all of its pending messages - the rule is called for each queue containing messages awaiting transmission. The rule decides whether to allow transmission of those messages for the supplied queue. The default behaviour if this rule is not implemented is to allow the operation. The rule implementation must be mapped to fPtrTransmitQueue in the user's rules initialisation function.
if (!timeToTransmit()) { // if not OK to transmit SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA); } |
|
function pointer type signature for a rules plugin TransmitQMgr function implementation.
Points to a rule which can allow or prevent the triggering of communications (where communications includes both the transmission of pending messages from remote asynchronous queue definitions and the stimulation of the Home Server Queue into polling its Store-and-Forward Queue). The rule is called from the queue manager's triggerTransmission function. The default behaviour if this rule is not implemented is to allow the operation. The rule implementation must be mapped to fPtrTransmitQMgr in the user's rules initialisation function.
// allow transmission to be triggered only if the number of pending messages is 10 or more if(pInput->msgsPendingTransmission < 10) { SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA); } |
|
function pointer type signature for a rules plugin UndoQMgr function implementation.
Points to a rule called when an undo operation is performed. This rule is for notification purposes only and has no affect on subsequent behaviour The rule implementation must be mapped to fPtrUndoQMgr in the user's rules initialisation function.
//log the operation MQECHAR * qMgrName; MQEINT32 size; rc = mqeString_getUtf8( (pInput->hQueue_QueueManagerName, pExceptBlock, NULL, &size); if(MQERETURN_OK == rc) { rc = mqeString_getUtf8(pInput->hQueue_QueueManagerName, pExceptBlock, qMgrName, &size); if(MQERETURN_OK == rc && pRulesInstance->ifp) { fprintf(pRulesInstance->ifp, "Undo operation on queue manager %s\n", qMgrName); } } |
|
function pointer type signature for a rules plugin ActivateQueue function implementation.
Points to a rule called when a queue is activated. The rule cannot prevent the activation of the queue so there is no default behaviour if the rule is not implemented. The rule implementation must be mapped to fPtrActivateQueue in the user's rules initialisation function.
MQECHAR * qName; MQEINT32 size; ... rc = mqeString_getUtf8(pInput->hQueueName, pExceptBlock, NULL, &size); if(MQERETURN_OK == rc) { mqeString_getUtf8(pInput->hQueueName, pExceptBlock, qName, &size); if(MQERETURN_OK == rc) { fprintf(pRulesInstance->ifp, "Activating queue %s \n", qName); } } |
|
function pointer type signature for a rules plugin BrowseMessage function implementation.
Points to a rule called when a filter is being applied during a browseMessage() operation. The rule can allow or reject the operation via the return code. The default behaviour if the rule is not implemented is to allow the operation. The rule implementation must be mapped to fPtrBrowseMessage in the user's rules initialisation function.
MQeStringHndl hFieldName, hFieldValue, hCompare; MQEBOOL contains = MQE_FALSE; ... // filter based on the value of a particular message field rc = mqeString_newUtf8(pExceptBlock, hFieldName, "MsgType"); rc = mqeFields_contains(hFilter, pExceptBlock, &contains, hFieldName); if(MQERETURN_OK == rc && contains) { mqeFields_getAscii(hFilter,pExceptBlock,&hFieldValue,hFieldName); if(MQERETURN_OK == rc) { MQEBOOL isEqual = MQE_FALSE; mqeString_newUtf8(pExceptBlock,hCompare,"OrderResponse"); rc = mqeString_equalTo(hCompare,pExceptBlock,&isEqual,hFieldValue); if(MQERETURN_OK == rc && !isEqual) { // only allow the action if the MsgType is OrderResponse SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA); } } } else { ... |
|
function pointer type signature for a rules plugin CloseQueue function implementation.
Points to a rule called when a queue is closed. The rule cannot prevent the closure of the queue so there is no default behaviour for when the rule is not implemented. The rule implementation must be mapped to fPtrCloseQueue in the user's rules initialisation function.
MQECHAR * qName; MQEINT32 size; ... rc = mqeString_getUtf8(pInput->hQueueName, pExceptBlock, NULL, &size); if(MQERETURN_OK == rc) { mqeString_getUtf8(pInput->hQueueName, pExceptBlock, qName, &size); if(MQERETURN_OK == rc) { fprintf(pRulesInstance->ifp, "Closing queue %s \n", qName); } } |
|
function pointer type signature for a rules plugin DuplicateMessage function implementation.
Points to a rule called when a duplicate message is put on a queue. The return code is not used to determine subsequent action and there is no default behaviour for when the rule is not implemented. The rule implementation must be mapped to fPtrDuplicateMessage in the user's rules initialisation function.
MqeStringHndl hQueueManagerName; MQEINT64 msgTimestamp; // get message UID fields rc = mqeFieldsHelper_getMsgOriginQMgr(hMsg, pExceptBlock, &hQueueManagerName); if(MQERETURN_OK == rc) { rc = mqeFieldsHelper_getMsgTimeStamp((hMsg,pExceptBlock,&msgTimestamp); if(MQERETURN_OK == rc) { MQEINT32 size; MQECHAR * queueMgrName; rc = mqeString_getUtf8(hQueueManagerName,pExceptBlock,NULL,&size); rc = mqeString_getUtf8(hQueueManagerName,pExceptBlock,queueMgrName,&size); if(MQERETURN_OK = rc) { //log the duplicate message event fprintf(pRulesInstance->ifp, "Duplicate message with uuid fields %s and %d\n", queueMgrName, msgTimestamp); } } } ... |
|
function pointer type signature for a rules plugin GotMessage function implementation.
Points to a rule called when a message has been retrieved from a queue which matches a filter specified in a getMessage operation. The rule can determine whether the message satisfies the getMessage request or not. The default behaviour is to allow the request to be satisfied - this can be altered by a return code of MQERETURN_RULES_DISALLOWED_BY_RULE. The rule implementation must be mapped to fPtrGotMessage in the user's rules initialisation function.
// does the message contain a field which states what operations are // allowed upon it? rc = mqeString_newUtf8(pExceptBlock, hFieldName, "AllowableOperations"); rc = mqeFields_contains(hFilter, pExceptBlock, &contains, hFieldName); if(MQERETURN_OK == rc && contains) { mqeFields_getAscii(hFilter,pExceptBlock,&hFieldValue,hFieldName); if(MQERETURN_OK == rc) { MQEBOOL isEqual = MQE_FALSE; mqeString_newUtf8(pExceptBlock,hCompare,"BrowseOnly"); rc = mqeString_equalTo(hCompare,pExceptBlock,&isEqual,hFieldValue); if(MQERETURN_OK == rc && isEqual) { // if the message states that it is browse only, disallow the operation SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA); } } } else { ... |
|
function pointer type signature for a rules plugin BrowsedMessage function implementation.
Points to a rule called when a message has been retrieved from a queue which matches a filter specified in a browseMessage operation. The rule can determine whether the message satisfies the browseMessage request or not. The default behaviour is to allow the request to be satisfied - this can be altered by a return code of MQERETURN_RULES_DISALLOWED_BY_RULE. The rule implementation must be mapped to fPtrBrowsedMessage in the user's rules initialisation function.
|
|
function pointer type signature for a rules plugin MessageExpired function implementation.
Points to a rule called when a message has exceeded either the queue's or its own expiry interval. The rule is for notification purposes only and cannot affect subsequent behaviour. The rule implementation must be mapped to fPtrMessageExpired in the user's rules initialisation function.
MQEBOOL contains = MQE_FALSE; MQeFieldsHndl hMsg; // Place a copy of the message on the dead letter queue // Set re-send flag so that attempt to put message to new queue isn't rejected // First, clone the message as the input parameter is read-only rc = mqeFields_clone(pInput->hMsg, pExceptBlock, &hMsg); if(MQERETURN_OK == rc) { rc = mqeFields_putBoolean(pInput->hMsg, pExceptBlock, MQE_MSG_RESEND, MQE_TRUE); if(MQERETURN_OK == rc) { // if the message contains an expiry interval field - remove it rc = mqeFields_contains(pInput->hMsg, pExceptBlock, &contains, MQE_MSG_EXPIRETIME); if(MQERETURN_OK == rc && contains) { rc = mqeFields_delete(pInput->hMsg, pExceptBlock, MQE_MSG_EXPIRETIME); } if(MQERETURN_OK == rc) { // put message onto dead letter queue MQeStringHndl hQueueManagerName; rc = mqeQueueManager_getName( hQueueManager, pExceptBlock, &hQueueManagerName); if(MQERETURN_OK == rc) { // use a temporary exception block as don't care if dead letter queue does not exist MQeExceptBlock tempExceptBlock; SET_EXCEPT_BLOCK_TO_DEFAULT(&tempExceptBlock); rc = mqeQueueManager_putMessage( hQueueManager, &tempExceptBlock, hQueueManagerName, MQE_DEADLETTER_QUEUE_NAME, pInput->hMsg, NULL, 0); (MQEVOID)mqeString_free(hQueueManagerName,&tempExceptBlock); } } } } |
|
function pointer type signature for a rules plugin TransmitMessage function implementation.
Points to a rule called prior to the transmission of an individual message from a remote asynchronous queue . The rule decides whether to allow the message to be transmitted - the default behaviour is to allow transmission. The rule implementation must be mapped to fPtrTransmitMessage in the user's rules initialisation function.
MQEBOOL contains; MQEINT32 priority; // only allow transmission if the message has a priority of greater than 4 rc = mqeFields_contains(pInput->hMsg, pExceptBlock, contains, MQE_MSG_PRIORITY); if(MQERETURN_OK == rc && contains == MQE_TRUE) { rc = mqeFields_getInt32(hMsg, pExceptBlock, &priority, MQE_MSG_PRIORITY); if(MQERETURN_OK == rc && priority < 5) { SET_EXCEPT_BLOCK(pExceptBlock,MQERETURN_RULES_DISALLOWED_BY_RULE, MQEREASON_NA); } } |
|
function pointer type signature for a rules plugin UndoQueue function implementation.
Points to a rule called when an undo operation is performed. The rule is invoked for each candidate message for the operation. The rule is for notification purposes only and has no affect upon subsequent behaviour The default behaviour if the rule is not implemented is to allow the operation. The rule implementation must be mapped to fPtrUndoQueue in the user's rules initialisation function.
// Log the match data uid fields
|
|
function pointer type signature for a rules plugin Free function implementation.
Points to a rule called when rules resources are being freed. This occurs when a queue manager is being freed as rules resources are tied to the lifecycle of a single queue manager. The rule may be used for clean-up of user-defined rules resources. There is no default behaviour if the rule is not implemented. The rule implementation must be mapped to fPtrFree in the user's rules initialisation function.
exampleRules_ * pRulesInstance = pInput->pPrivateData;
if(pRulesInstance->ifp != NULL) {
fclose(pRulesInstance->ifp);
}
|
|
function pointer type signature for a rules plugin New function implementation.
Sets up the information required for a user's rules implementation. It is the user's responsibility within this function to allocate memory for the rules instance structure and also to map rules functions to the user's implementation of those functions. It is not necessary to provide an implementation of each one of these functions. The default behaviour when an implementation is not provided is described under each function pointer typedef in this document. However, the initialization function itself must be implemented and its name mapped, together with the module name, to a class alias. The user must register the rules instance in his/her application by providing an alias which maps to two MQeStringHndls: the name of the plugin module and the name of the initialisation function. To do this, use the mqeClassAlias_add api. This alias is then used to register the rules instance. The registration of the rule must be done before the queue manager is created at the beginning of the application, e.g.: MQeQueueManagerParms qmParams; mqeString_newUtf8(pExceptBlk, &rulesIndex, "exampleRules"); // alias for the module / entry point mqeString_newUtf8(pExceptBlk, &moduleName, "exampleRules.dll"); // module mqeString_newUtf8(pExceptBlk, &entryPoint, "exampleRules_new"); // entry point mqeClassAlias_add(pExceptBlk, rulesIndex, moduleName, entryPoint); ... qmParams.hQueueStore = msgStore; // String parameters for the location of the msg store qmParams.hQueueManagerRules = rulesIndex; // Alias for rules module / entry point // Indicate what parts of the structure have been set qmParams.opFlags = QMGR_Q_STORE_OP | QMGR_RULES_OP; ...
MQERETURN MQEPUBLISHED exampleRules_new( MQeRulesNew_in_ * pInput , MQeRulesNew_out_ * pOutput) { exampleRules_ * pRulesInstance; // where exampleRules_ is a user_defined structure holding private data MQeExceptBlock * pExceptBlock; pExceptBlock = (MQeExceptBlock *) pOutput->pExceptBlock; SET_EXCEPT_BLOCK_TO_DEFAULT(pExceptBlock) ; // allocate the memory for the private data structure // this holds user's private data which can be accessed in all rules pRulesInstance = malloc(sizeof(exampleRules_)); if (pRulesInstance != NULL) { // set up function table and rules instance in output structure // map user rule function implementations to output structure function pointers pOutput->fPtrActivateQMgr = exampleRules_ActivateQMgr; pOutput->fPtrCloseQMgr = exampleRules_QueueManagerClose; pOutput->fPtrDeleteMessage = exampleRules_DeleteMessage; pOutput->fPtrGetMessage = exampleRules_GetMessage; pOutput->fPtrPutMessage = exampleRules_PutMessage; pOutput->fPtrActivateQueue = exampleRules_ActivateQueue; pOutput->fPtrCloseQueue = exampleRules_CloseQueue; pOutput->fPtrBrowseMessage = exampleRules_BrowseMessage; pOutput->fPtrFree = exampleRules_free; pRulesInstance->carryOn = MQE_TRUE; pRulesInstance->triggerInterval = 6000; pRulesInstance->hAdmin = NULL; pRulesInstance->hThread = NULL; pRulesInstance->ifp = fopen("traceFile.txt","w"); pOutput->pPrivateData = (MQEVOID *)pRulesInstance; } else { // We had a problem so clear and report error SET_EXCEPT_BLOCK(... } return EC(pExceptBlock); } |