Application Callbacks

To use the full potential of PROFINET the stack allows you to interact at
several stages of the protocol. For example you can withhold the sending of the
application ready signal to the PLC or handle record data reads and writes to
specific slots.

The first thing to use the callback system is to provide a callback function
that the stack can call every time it wants to communicate with the application.
The callback function must have the following prototype:

    GOAL_STATUS_T appl_pnioCb(
        GOAL_PNIO_T *pHdlPnio,          /**< PROFINET handle */
        GOAL_PNIO_CB_ID_T id,           /**< callback id */
        GOAL_PNIO_CB_DATA_T *pCb        /**< callback parameters */
    );

It is registered with the call to goal_pnioNew which takes the pointer to
the callback function as second parameter.

    res = goal_pnioInit(&pPnio, APPL_PNIO_ID, appl_pnioCb);

Now every time the appl_pnioCb is called, the GOAL_PNIO_CB_ID_T
value contains the reason of the call. The GOAL_PNIO_CB_DATA_T structure
contains an array of multiple unions were each array element has a special
meaning depending on the GOAL_PNIO_CB_ID_T value.

The following subsections will provide you with the details on the available
callback ids.

GOAL_PNIO_CB_ID_ALARM_ACK_TIMEOUT - Timeout waiting for Alarm ACK

Indicate that a timeout occurred in APMS while waiting for an alarm acknowledge.

GOAL_PNIO_CB_ID_ALARM_NOTIFY_ACK - Alarm notification ACK received

Indicates that an alarm notification ACK was received.

GOAL_PNIO_CB_ID_ALARM_NOTIFY - Alarm notification received

Indicates that an alarm notification was received. If the callback isn't

handled or GOAL_OK is returned the PROFINET stack will automatically

acknowledge the received alarm notification.

GOAL_PNIO_CB_ID_APPL_READY - Application Ready Response Received

Indicate that an application ready response was received. The return value has

to be GOAL_OK.

GOAL_PNIO_CB_ID_BLINK - Blink Request

Indicates that a DCP signal request was received and fills the callback data

with the necessary information.

pCb->data[0].stateDcpBlink tells the application the initial signal request

(START), the correct time to toggle the signal (TOGGLE) and when the signal

phase is over (FINISH). This information can be used if the application wants

to fully represent the signal by itself.

The second possibility is to use the cb->data[1].stateDcpLight data which

contains either GOAL_PNIO_DCP_LIGHT_OFF or GOAL_PNIO_DCP_LIGHT_ON which

can be used to handover the signal indicator directly to a LED or blink

function.

If variant 1 or 2 is used than the callback has to return GOAL_OK_SUPPORTED

otherwise the stack handles the blinking by itself by calling goal_targetSetLeds with

the GOAL_PNIO_LED_SIGNAL define. For stack internal handling the implementation

of goal_targetGetLeds and goal_targetSetLeds is mandatory.

    case GOAL_PNIO_CB_ID_BLINK:

#if FIRST_SCENARIO
        /**************************************/
        /* first scenario: act on blink state */
        /**************************************/
        switch (pCb->data[0].stateDcpBlink) {

            case GOAL_PNIO_DCP_BLINK_START:
                /* start blinking */
                break;

            case GOAL_PNIO_DCP_BLINK_TOGGLE:
                /* toggle signal */
                break;

            case GOAL_PNIO_DCP_BLINK_FINISH:
                /* switch signal off */
                break;
        }

        res = GOAL_OK_SUPPORTED;
        break;
#endif /* FIRST_SCENARIO */

#if SECOND_SCENARIO
        /***************************************/
        /* second scenario: act on light state */
        /***************************************/
        vendorBlinkFunction(pCb->data[1].stateDcpLight);
        res = GOAL_OK_SUPPORTED;
        break;
#endif /* SECOND_SCENARIO */

#if THIRD_SCENARIO
        /**************************************************************/
        /* third scenario: do nothing / PROFINET stack handles signal */
        /**************************************************************/
#endif /* THIRD_SCENARIO */

GOAL_PNIO_CB_ID_CONNECT_FINISH - Connect Request Done

Indicates that a connect request was fully processed and allows the application

to cancel it by setting the error status and return a value that is not

GOAL_OK.

GOAL_PNIO_CB_ID_CONNECT_REQUEST - Connect Request

Indicates that the processing of a connect request has been started.

The parameter pointer is set to NULL.

GOAL_PNIO_CB_ID_CONNECT_REQUEST_EXP_START - Expected Submodule Block Start

Indicates that an expected submodule block starts. This can be used to unplug

all modules before the request callback for each module comes in.

GOAL_PNIO_CB_ID_END_OF_PARAM - Param End Received

Indicates that the parameter end information was received.

GOAL_PNIO_CB_ID_END_OF_PARAM_PLUG - Plug Param End Received

Indicates the the plug parameter end information was received.

GOAL_PNIO_CB_ID_EXP_SUBMOD - Expected Submodule

Indicates an expected submodule which can be plugged immediately.

GOAL_PNIO_CB_ID_FACTORY_RESET - Factory Reset

Indicates a factory reset.

The parameter pointer is set to NULL.

GOAL_PNIO_CB_ID_IO_DATA_TIMEOUT - Cyclic Timeout

Indicates that an output endpoint timed out.

GOAL_PNIO_CB_ID_NET_IP_SET - IP Configuration Update

Indicate that the IP configuration was updated. The internal change flag

indicates if the change was triggered by PROFINET DCP (PN_TRUE) or by an

external caller like DHCP (PN_FALSE).

GOAL_PNIO_CB_ID_NEW_AR - New Application Relation

Indicates a new application relation. A return value different from GOAL_OK

drops the AR and replies with an error.

GOAL_PNIO_CB_ID_NEW_IO_DATA - New IO Data

Indicates reception of new IO data.

GOAL_PNIO_CB_ID_PLUG_READY - Plug Ready Response Received

Indicates that a plug ready response was received.

GOAL_PNIO_CB_ID_READ_RECORD - Read Record Data

Indicates that record data that couldn't be handled by the stack itself should

be read. Before this callback is called, the stack checks if the API, slot

and subslot combination is valid.

If the function returns GOAL_OK the request will be denied with "invalid

index".

To handle the request the callback needs to return GOAL_OK_SUPPORTED. It can

either respond directly or later by calling goal_pnioRecReadFinish. Also the

now PROFINET status can be set through goal_pnioRecReadFinish.

If the response isn't GOAL_OK or GOAL_OK_SUPPORTED the stack will

automatically respond with application read error.

The parameter "sequence number" is used later when the response is send to

detect if the request has expired.

GOAL_PNIO_CB_ID_RELEASE_AR - Release Application Relation

Indicates that an application relation was released.

GOAL_PNIO_CB_ID_RESET_TO_FACTORY - Reset To Factory

Indicates a reset to factory request. If there is a separate request handling

outside of the stack the application must return GOAL_OK_SUPPORTED.

If the application doesn't return from the callback with GOAL_OK or

GOAL_OK_SUPPORTED the DCP error "0x04 suboption not set" is sent back to the

DCP set request sender.

GOAL_PNIO_CB_ID_STATION_NAME - Station Name Changed

Indicates a station name change. If the permanent flag is set to GOAL_TRUE,

the station name is stored in NVS, otherwise the station name is only stored

temporary and the NVS value is cleared.

GOAL_PNIO_CB_ID_WRITE_RECORD - Write Record Data

Indicates that record data that couldn't be handled by the stack itself should

be written. Before this callback is called, the stack checks if the API, slot

and subslot combination is valid.

If the function returns GOAL_OK the request will be denied with "invalid

index".

To handle the request the callback needs to return GOAL_OK_SUPPORTED. It can

either respond directly or later by calling goal_pnioRecWriteFinish. Also the

now PROFINET status can be set through goal_pnioRecWriteFinish.

If the response isn't GOAL_OK or GOAL_OK_SUPPORTED the stack will

automatically respond with application read error.

The parameter "sequence number" is used later when the response is send to

detect if the request has expired.

GOAL_PNIO_CB_ID_INIT - Stack initialized

Indicates that the PROFINET stack is fully initialized. The parameter pointer

is set to NULL. At this point it is safe to create the device configuration.

GOAL_PNIO_CB_ID_LLDP_UPDATE - LLDP Update

Signalizes that the device on the partner port changed.

GOAL_PNIO_CB_ID_CONN_REQ_EXP_FINISH - Connect Request Expected Submodule Block Finish

This callback is called after the Expected Submodule Block in the Connect

Request has been parsed.

GOAL_PNIO_CB_ID_STATION_NAME_VERIFY - DCP Station Name Verification

Let the application verify a DCP Station Name Set Request.

If the function returns a GOAL error status the set request will be denied.

GOAL_PNIO_CB_ID_NET_IP_SET_VERIFY - DCP IP Configuration Verification

Let the application verify a DCP IP Configuration Set Request.

If the function returns a GOAL error status the set request will be denied.