Returning a `CGEvent` of my own creation in `NSEventTap`

Question

Documentation for CGEventTapCallBack here states:

CGEventRef event The incoming event. This event is owned by the caller, and you do not need to release it.

What happens if I wish to eat the event, and return NULL? Should I CFRelease it myself?

Similarly, if I wish to replace it with an event I have created myself, should I CFRelease the incoming event and CFRetain the newly created event?

Or am I constrained to modifying the contents of the received CGEvent in-place? And is this is indeed the case, is there any API-call I can use hot-swap?

Answer 1

Copied from the documentation for CGEventTapCallBack (link in the question):

Discussion

If the event tap is an active filter, your callback function should return one of the following:

• The (possibly modified) event that is passed in. This event is passed back to the event system.

• A newly-constructed event. After the new event has been passed back to the event system, the new event will be released along with the original event.

• NULL if the event passed in is to be deleted.

The new event will be released along with the original event. Don't release the original event and don't release the new event.