External events

When an asynchronous event is fired (for example, barcode reading), an object can use the IAsyncEvent interface for creating an external event in 1C:Enterprise. The IAsyncEvent interface inherits from IUnknown. All events are queued and processed in the order they are added. The number of stored events is limited to the queue size. During the initialization, the queue size is set to 1 and then it can be changed by calling the SetEventBufferDepth() method and retrieved using the GetEventBufferDepth() method. A separate queue is maintained for each add-in object. External event processing is performed using the predefined ExternEventProcessing() procedure and external event handlers in form modules.

SetEventBufferDepth

Description:

Sets the event queue size for an object. If the number of events in the queue exceeds the queue size, the latest events are deleted.

Syntax:

HRESULT SetEventBufferDepth(long lDepth);

Parameters:

lDepth

Type: long. The event queue size.

Return value:

  • S_OK - the event queue size is successfully set.
  • E_FAIL - an error occurred while setting the event queue size.

  • Other return codes that inform about errors are possible.

GetEventBufferDepth

Description:

Stores the event queue size of the specified object to the plDepth variable.

Syntax:

HRESULT GetEventBufferDepth(long* plDepth);

Parameters:

plDepth

Type: long*. Pointer to the variable that will contain the event queue size.

Return value:

  • S_OK -the event queue size is successfully obtained.
  • E_FAIL - an error occurred while getting the event queue size.

  • Other return codes that inform about errors are possible.

ExternalEvent

Description:

Adds an event to the queue, storing the event source, name, and parameters. During event processing, that data is passed to the ExternEventProcessing() procedure. Once the ExternalEvent() method is called, the event processing is performed as follows:

  1. The event is stored to the event queue (if the queue is full, the event is lost).

  2. If no system events are available and the queue is not empty, the first event is taken from the queue.

  3. External event processing is started.

This procedure is repeated for all add-in objects, so that external event processing is synchronized with system event processing.

Syntax:

HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData);

Parameters:

bstrWho

Type: BSTR. A string that contains the event source.

bstrWhat

Type: BSTR. A string that contains the event name.

bstrData

Type: BSTR. A string that contains the event parameters.

Return value:

  • S_OK - the event is added to the queue.
  • E_FAIL - the queue is full, or unknown error.

  • E_OUTOFMEMORY - not enough memory.

  • Other return codes that inform about errors are possible.

CleanBuffer

Description:

Clears the event queue by deleting all events from the queue.

Syntax:

HRESULT CleanBuffer();

Return value:

  • S_OK - the queue is cleared.

  • E_FAIL - an error occurred while clearing the queue.

  • Other return codes that inform about errors are possible.

Next page: Status bar operations

Be the first to know tips & tricks on business application development!

A confirmation e-mail has been sent to the e-mail address you provided .

Click the link in the e-mail to confirm and activate the subscription.