These functions install the necessary callback functions that allow RFC servers to process incoming RFC, tRFC, qRFC and bgRFC calls. More...

Functions
DECL_EXP RFC_RC SAP_API	RfcInstallAuthenticationCheckHandler (RFC_ON_AUTHENTICATION_CHECK onAuthenticationCheck, RFC_ERROR_INFO *errorInfo)
	Installs an optional function for performing authentication checks on incoming login attempts. More...

DECL_EXP RFC_RC SAP_API	RfcInstallServerFunction (SAP_UC const sysId, RFC_FUNCTION_DESC_HANDLE funcDescHandle, RFC_SERVER_FUNCTION serverFunction, RFC_ERROR_INFO errorInfo)
	Installs a callback function of type RFC_SERVER_FUNCTION, which will be triggered when a request for the function module corresponding to funcDescHandle comes in from the R/3 system corresponding to sysId. More...

DECL_EXP RFC_RC SAP_API	RfcInstallGenericServerFunction (RFC_SERVER_FUNCTION serverFunction, RFC_FUNC_DESC_CALLBACK funcDescProvider, RFC_ERROR_INFO *errorInfo)
	Installs a generic callback function of type RFC_SERVER_FUNCTION together with a callback function of type RFC_FUNC_DESC_CALLBACK for obtaining the metadata description of unknown function modules. More...

DECL_EXP RFC_RC SAP_API	RfcInstallTransactionHandlers (SAP_UC const sysId, RFC_ON_CHECK_TRANSACTION onCheckFunction, RFC_ON_COMMIT_TRANSACTION onCommitFunction, RFC_ON_ROLLBACK_TRANSACTION onRollbackFunction, RFC_ON_CONFIRM_TRANSACTION onConfirmFunction, RFC_ERROR_INFO errorInfo)
	Installs the necessary callback functions for processing incoming tRFC/qRFC calls. More...

DECL_EXP RFC_RC SAP_API	RfcInstallBgRfcHandlers (SAP_UC const sysId, RFC_ON_CHECK_UNIT onCheckFunction, RFC_ON_COMMIT_UNIT onCommitFunction, RFC_ON_ROLLBACK_UNIT onRollbackFunction, RFC_ON_CONFIRM_UNIT onConfirmFunction, RFC_ON_GET_UNIT_STATE onGetStateFunction, RFC_ERROR_INFO errorInfo)
	Installs the necessary callback functions for processing incoming bgRFC calls. More...

DECL_EXP RFC_RC SAP_API	RfcInstallPassportManager (RFC_PM_CALLBACK onClientCallStart, RFC_PM_CALLBACK onClientCallEnd, RFC_PM_CALLBACK onServerCallStart, RFC_PM_CALLBACK onServerCallEnd, RFC_ERROR_INFO *errorInfo)
	Installs the necessary callback functions for processing Extended Passport (EPP) events. More...

DECL_EXP RFC_RC SAP_API	RfcInstallPasswordChangeHandler (RFC_ON_PASSWORD_CHANGE onPasswordChange, RFC_ERROR_INFO *errorInfo)
	Installs an optional callback function for processing password change events. More...

DECL_EXP RFC_RC SAP_API	RfcInstallAuthorizationCheckHandler (RFC_ON_AUTHORIZATION_CHECK onAuthorizationCheck, RFC_ERROR_INFO *errorInfo)
	Installs an optional callback function for performing authorization checks on incoming function calls. More...

Detailed Description

These functions install the necessary callback functions that allow RFC servers to process incoming RFC, tRFC, qRFC and bgRFC calls.

Function Documentation

DECL_EXP RFC_RC SAP_API RfcInstallAuthenticationCheckHandler	(	RFC_ON_AUTHENTICATION_CHECK	onAuthenticationCheck,
		RFC_ERROR_INFO *	errorInfo
	)

Installs an optional function for performing authentication checks on incoming login attempts.

After an RFC connection is opened to the RFC library, and before the first RFC call is executed over this connection, the RFC library calls this callback function, if installed. Here you can implement a central authentication check, defining exactly which entity is allowed to execute the function in your RFC server program. The actual function module implementations can then concentrate on their business logic and don't need to pay attention to access and authentication checks.

Parameters

[in]	onAuthenticationCheck	Pointer to a function of type RFC_ON_AUTHENTICATION_CHECK. The RFC lib calls this function, whenever a new RFC connection to this server is first opened by the client.
[out]	*errorInfo	Additional information, in case the handler could not be installed.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcInstallAuthorizationCheckHandler	(	RFC_ON_AUTHORIZATION_CHECK	onAuthorizationCheck,
		RFC_ERROR_INFO *	errorInfo
	)

Installs an optional callback function for performing authorization checks on incoming function calls.

After an RFC call arrives at the RFC library, and before the library executes the corresponding server implementation for that function module, it calls this callback function, if installed. Here you can implement a central authorization check, defining exactly which user from which backend system is allowed to execute what functions in your RFC server program. The actual function module implementations can then concentrate on their business logic and don't need to pay attention to access and authorization checks.

Parameters

[in]	onAuthorizationCheck	Pointer to a function of type RFC_ON_AUTHORIZATION_CHECK. The RFC lib calls this function, whenever an RFC request arrives from the backend.
[out]	*errorInfo	Additional information, in case the handler could not be installed.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcInstallBgRfcHandlers	(	SAP_UC const *	sysId,
		RFC_ON_CHECK_UNIT	onCheckFunction,
		RFC_ON_COMMIT_UNIT	onCommitFunction,
		RFC_ON_ROLLBACK_UNIT	onRollbackFunction,
		RFC_ON_CONFIRM_UNIT	onConfirmFunction,
		RFC_ON_GET_UNIT_STATE	onGetStateFunction,
		RFC_ERROR_INFO *	errorInfo
	)

Installs the necessary callback functions for processing incoming bgRFC calls.

These functions need to be implemented by you and will be used by the RFC runtime in the following way:

The RFC_ON_CHECK_UNIT function is called when a local background unit is starting. Since a background RFC call can be issued many times by the client system, the function is responsible for storing the unit ID and type in permanent storage. The return value should be one of the following:
- RFC_OK
  Unit ID stored, LUW can be started.
- RFC_EXECUTED
  This LUW has already been processed successfully in an earlier attempt. Skip the execution now.
- RFC_EXTERNAL_FAILURE
  Currently unable to access my permanent storage. Raise an exception in the sending system, so that the sending system will try to resend the unit at a later time.
The next step will be the execution of the RFC_SERVER_FUNCTIONs for all function modules contained in the LUW.
If one of the RFC_SERVER_FUNCTION implementations returns an error code, RFC_ON_ROLLBACK_UNIT is called. Here you should roll back all the work of all the previous RFC_SERVER_FUNCTIONs. (The easiest way is to do a database ROLLBACK WORK here.)
If all RFC_SERVER_FUNCTIONs complete successfully, RFC_ON_COMMIT_UNIT is called at the end. Persist all the changes here (e.g. do a COMMIT WORK).
Note: Normally you'll only have "one-function-module LUWs", e.g. IDocs. In this case the RFC_SERVER_FUNCTION can already commit/rollback its own work, before returning RFC_OK or an error code. So the two functions RFC_ON_ROLLBACK_UNIT and RFC_ON_COMMIT_UNIT can be empty in this case.
In the end RFC_ON_CONFIRM_UNIT will be called. All information stored about that LUW can now be discarded by the server, as it no longer needs to protect itself against duplicates. In general this function can be used to delete the unit ID from permanent storage.
At various points in the processing of a background unit, the backend system may or may not inquire the status of the currently (or previously) processed unit by calling RFC_ON_GET_UNIT_STATE. Your implementation of this function should check your permanent storage for status information about the given unit ID and fill the RFC_UNIT_STATE* accordingly.

If you pass NULL as "sysId", the transaction handlers will be used for bgRFC calls from any backend system, for which no explicit handlers have been installed.

Parameters

[in]	*sysId	System ID of the SAP system for which to use this set of transaction handlers, or NULL.
[in]	onCheckFunction	Pointer to a function of type RFC_ON_CHECK_UNIT.
[in]	onCommitFunction	Pointer to a function of type RFC_ON_COMMIT_UNIT.
[in]	onRollbackFunction	Pointer to a function of type RFC_ON_ROLLBACK_UNIT.
[in]	onConfirmFunction	Pointer to a function of type RFC_ON_CONFIRM_UNIT.
[in]	onGetStateFunction	Pointer to a function of type RFC_ON_GET_UNIT_STATE.
[out]	*errorInfo	Additional information, in case the handlers could not be installed.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcInstallGenericServerFunction	(	RFC_SERVER_FUNCTION	serverFunction,
		RFC_FUNC_DESC_CALLBACK	funcDescProvider,
		RFC_ERROR_INFO *	errorInfo
	)

Installs a generic callback function of type RFC_SERVER_FUNCTION together with a callback function of type RFC_FUNC_DESC_CALLBACK for obtaining the metadata description of unknown function modules.

The RFC Runtime calls the callback function RFC_SERVER_FUNCTION, if it receives a function call, for whose function module name no matching callback function has been installed via RfcInstallServerFunction() (neither for the current system ID nor for SysID=NULL).

In addition to the handler function you need to provide a second callback function: RFC_FUNC_DESC_CALLBACK. The RFC runtime calls it to obtain an RFC_FUNCTION_DESC_HANDLE for the current function module from you. So this function either needs to return hardcoded meta data or needs to be able to perform a DDIC lookup using a valid client connection and RfcGetFunctionDesc(). If your implementation of RFC_FUNC_DESC_CALLBACK is not able to provide a function description for the current function module name, it should return RFC_NOT_FOUND. The RFC runtime will then notify the backend, that this function module cannot be processed by your RFC server.

Parameters

[in]	serverFunction	A pointer to a function that can handle "all" function modules.
[in]	funcDescProvider	A pointer to a function that can provide metadata descriptions of "all" function modules.
[out]	*errorInfo	Again not much that can go wrong at this point.

Returns

DECL_EXP RFC_RC SAP_API RfcInstallPassportManager	(	RFC_PM_CALLBACK	onClientCallStart,
		RFC_PM_CALLBACK	onClientCallEnd,
		RFC_PM_CALLBACK	onServerCallStart,
		RFC_PM_CALLBACK	onServerCallEnd,
		RFC_ERROR_INFO *	errorInfo
	)

Installs the necessary callback functions for processing Extended Passport (EPP) events.

Extended Passports is a feature that supersedes Distributed Statistical Records (DSRs). It allows to track certain performance attributes across system boundaries. These callback functions allow the application to exchange passports with the backend system. The actual data contained in the passports, can be processed with the eppslib library.

Note: Normal RFC applications should never need to deal with this topic at all...

Parameters

[in]	onClientCallStart	Pointer to a function of type RFC_PM_CALLBACK. The RFC lib calls this function, before it sends a client request into the backend. Here you can provide the passport that is to be sent along with the RFC request.
[in]	onClientCallEnd	Pointer to a function of type RFC_PM_CALLBACK. The RFC lib calls this function, after the RFC response was received from the backend. You can read the updated passport information.
[in]	onServerCallStart	Pointer to a function of type RFC_PM_CALLBACK. The RFC lib calls this function, when it received an RFC request from the backend. Here you can read the passport that accompanied the request.
[in]	onServerCallEnd	Pointer to a function of type RFC_PM_CALLBACK. The RFC lib calls this function, before it will send the response to the above request back to the backend. You can update the passport data with information about processing performance of the current call.
[out]	*errorInfo	Additional information, in case the handlers could not be installed.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcInstallPasswordChangeHandler	(	RFC_ON_PASSWORD_CHANGE	onPasswordChange,
		RFC_ERROR_INFO *	errorInfo
	)

Installs an optional callback function for processing password change events.

Whenever a logon attempt is made with a user, whose password is still initial, the backend system challenges this user to change his/her password. If this happens during a call to RfcOpenConnection(), the RFC library calls this callback function (if installed), and allows you to change the user's password. In your implementation, you can either return RFC_EXTERNAL_FAILURE, if you can't/don't want to change the password. In that case RfcOpenConnection() will end with RFC_LOGON_FAILURE and any additional text from errorInfo->message will be returned to the application. Or you can fill the old and new password with correct values and return RFC_OK, upon which the RFC library will attempt to change the password accordingly.

Note: See also the documentation of the logon parameter PASSWORD_CHANGE_ENFORCED in the sample sapnwrfc.ini file, which specifies, whether the application is allowed to get by without a PasswordChangeHandler and keep using the initial/expired password for login.

Parameters

[in]	onPasswordChange	Pointer to a function of type RFC_ON_PASSWORD_CHANGE. The RFC lib calls this function, whenever an initial password is detected during a call to RfcOpenConnection().
[out]	*errorInfo	Additional information, in case the handler could not be installed.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcInstallServerFunction	(	SAP_UC const *	sysId,
		RFC_FUNCTION_DESC_HANDLE	funcDescHandle,
		RFC_SERVER_FUNCTION	serverFunction,
		RFC_ERROR_INFO *	errorInfo
	)

Installs a callback function of type RFC_SERVER_FUNCTION, which will be triggered when a request for the function module corresponding to funcDescHandle comes in from the R/3 system corresponding to sysId.

If you pass NULL as "sysId", the serverFunction will be used for calls from any backend system.

The main inputs of RFC_SERVER_FUNCTION are as follows:

RFC_CONNECTION_HANDLE
A connection handle, which can be used to query logon information about the current (backend) user or to make callbacks into the backend.
RFC_FUNCTION_HANDLE
A data container that represents the current function call. Read the importing parameters, which came from the backend, from this container via the RfcGetX functions and write the exporting parameters, which are to be returned to the backend, into this container using the RfcSetX functions.
The memory of that container is automatically released by the RFC Runtime after the RFC_SERVER_FUNCTION returns.
RFC_ERROR_INFO*
If you want to return an ABAP Exception or ABAP Message to the backend, fill the parameters of that container and return RFC_ABAP_EXCEPTION or RFC_ABAP_MESSAGE from your RFC_SERVER_FUNCTION implementation.
If you want to return a SYSTEM_FAILURE to the backend, fill the message parameter of this container and return RFC_EXTERNAL_FAILURE from your RFC_SERVER_FUNCTION implementation. If your RFC_SERVER_FUNCTION implementation processed the function call successfully, you should return RFC_OK.

Parameters

[in]	*sysId	System ID of the R/3 system, for which this function module implementation shall be used. If you set this to NULL, this server function will be used for calls from all backends, for whose SysID no explicit server function has been installed.
[in]	funcDescHandle	A function description giving the name of the function module and its parameters. Note that the NW RFC library does not create a copy of this function description. So if you are using self-defined (hard-coded) function descriptions (see RfcCreateFunctionDesc()), then you need to make sure, that these function descriptions are not destroyed as long as they are still used in a server function installation!
[in]	serverFunction	Pointer to a C function of type RFC_SERVER_FUNCTION. If you pass a null-pointer here, any previously installed server function for the given function module will be uninstalled.
[out]	*errorInfo	Not much that can go wrong here.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcInstallTransactionHandlers	(	SAP_UC const *	sysId,
		RFC_ON_CHECK_TRANSACTION	onCheckFunction,
		RFC_ON_COMMIT_TRANSACTION	onCommitFunction,
		RFC_ON_ROLLBACK_TRANSACTION	onRollbackFunction,
		RFC_ON_CONFIRM_TRANSACTION	onConfirmFunction,
		RFC_ERROR_INFO *	errorInfo
	)

Installs the necessary callback functions for processing incoming tRFC/qRFC calls.

These functions need to be implemented by you and will be used by the RFC runtime in the following way:

The RFC_ON_CHECK_TRANSACTION function is called when a local transaction is starting. Since a transactional RFC call can be issued many times by the client system, the function is responsible for storing the transaction ID in permanent storage. The return value should be one of the following:
- RFC_OK
  Transaction ID stored, transaction can be started.
- RFC_EXECUTED
  This transaction has already been processed successfully in an earlier attempt. Skip the execution now.
- RFC_EXTERNAL_FAILURE
  Currently unable to access my permanent storage. Raise an exception in the sending system, so that the sending system will try to resend the transaction at a later time.
The next step will be the execution of the RFC_SERVER_FUNCTIONs for all function modules contained in the LUW.
If one of the RFC_SERVER_FUNCTION implementations returns an error code, RFC_ON_ROLLBACK_TRANSACTION is called. Here you should roll back all the work of all the previous RFC_SERVER_FUNCTIONs. (The easiest way is to do a database ROLLBACK WORK here.)
If all RFC_SERVER_FUNCTIONs complete successfully, RFC_ON_COMMIT_TRANSACTION is called at the end. Persist all the changes here (e.g. do a COMMIT WORK).
Note: Normally you'll only have "one-function-module LUWs", e.g. IDocs. In this case the RFC_SERVER_FUNCTION can already commit/rollback its own work, before returning RFC_OK or an error code. So the two functions RFC_ON_ROLLBACK_TRANSACTION and RFC_ON_COMMIT_TRANSACTION can be empty in this case.
In the end RFC_ON_CONFIRM_TRANSACTION will be called. All information stored about that transaction can now be discarded by the server, as it no longer needs to protect itself against duplicates. In general this function can be used to delete the transaction ID from permanent storage.

If you pass NULL as "sysId", the transaction handlers will be used for tRFC calls from any backend system, for which no explicit handlers have been installed.

Parameters

[in]	*sysId	System ID of the SAP system for which to use this set of transaction handlers, or NULL.
[in]	onCheckFunction	Pointer to a function of type RFC_ON_CHECK_TRANSACTION.
[in]	onCommitFunction	Pointer to a function of type RFC_ON_COMMIT_TRANSACTION.
[in]	onRollbackFunction	Pointer to a function of type RFC_ON_ROLLBACK_TRANSACTION.
[in]	onConfirmFunction	Pointer to a function of type RFC_ON_CONFIRM_TRANSACTION.
[out]	*errorInfo	Additional information, in case the handlers could not be installed.

Returns: RFC_RC

Functions

Detailed Description

Function Documentation