Connection related API

Opening and closing client & server connections. More...

Modules
	API for Automated Servers
	Functions for managing "automated" Servers (also called "multi-count" Servers).

Classes
struct	_RFC_ATTRIBUTES
	Structure returned by RfcGetConnectionAttributes() giving some information about the partner system on the other side of this RFC connection. More...
struct	_RFC_SECURITY_ATTRIBUTES
	Structure passed to the RFC_SERVER_AUTHORIZATION_HANDLER giving some security related information about the calling ABAP partner of an incoming RFC call. More...
struct	_RFC_SERVER_CONTEXT
	Used in RfcGetServerContext() for obtaining more information about the current incoming function call. More...
struct	_RFC_CONNECTION_HANDLE
	Handle to an RFC connection (client connection or server connection). More...
struct	_RFC_CONNECTION_PARAMETER
	Structure used for connecting to a backend system via RfcOpenConnection() or RfcRegisterServer(). More...

Enumerations
enum	_RFC_CALL_TYPE { RFC_SYNCHRONOUS, RFC_TRANSACTIONAL, RFC_QUEUED, RFC_BACKGROUND_UNIT }
	Used in RfcGetServerContext() for inquiring the type of an incoming function call from the backend. More...
enum	_RFC_PROTOCOL_TYPE {   RFC_UNKOWN, RFC_CLIENT, RFC_STARTED_SERVER, RFC_REGISTERED_SERVER,   RFC_MULTI_COUNT_REGISTERED_SERVER, RFC_TCP_SOCKET_CLIENT, RFC_TCP_SOCKET_SERVER, RFC_WEBSOCKET_CLIENT,   RFC_WEBSOCKET_SERVER, RFC_PROXY_WEBSOCKET_CLIENT }
	Used in state information in order to indicate the different types of RFC programs, RFC Server types, etc. More...

Functions
DECL_EXP RFC_RC SAP_API	RfcGetSaplogonEntries (SAP_UC ***saplogonIDList, unsigned *numSaplogonIDs, RFC_ERROR_INFO *errorInfo)
	Returns a list of names of all SAP Systems maintained in SAPLogon (saplogon.ini or SAPUILandscape.xml). More...
DECL_EXP RFC_RC SAP_API	RfcFreeSaplogonEntries (SAP_UC ***saplogonIDList, unsigned *numSaplogonIDs, RFC_ERROR_INFO *errorInfo)
	Frees a list of SAPLogon IDs obtained from RfcGetSaplogonEntries(). More...
DECL_EXP RFC_RC SAP_API	RfcGetSaplogonEntry (SAP_UC *saplogonID, RFC_CONNECTION_PARAMETER **entryParameters, unsigned *numParameters, RFC_ERROR_INFO *errorInfo)
	Retrieves all connection parameters corresponding to the given ID from the saplogon.ini or SAPUILandscape.xml file. More...
DECL_EXP RFC_RC SAP_API	RfcFreeSaplogonEntry (RFC_CONNECTION_PARAMETER **entryParameters, unsigned *numParameters, RFC_ERROR_INFO *errorInfo)
	Frees an array of connection parameters obtained from RfcGetSaplogonEntry(). More...
DECL_EXP RFC_CONNECTION_HANDLE SAP_API	RfcOpenConnection (RFC_CONNECTION_PARAMETER const *connectionParams, unsigned paramCount, RFC_ERROR_INFO *errorInfo)
	Opens an RFC client connection for invoking ABAP function modules in an R/3 backend. More...
DECL_EXP RFC_CONNECTION_HANDLE SAP_API	RfcRegisterServer (RFC_CONNECTION_PARAMETER const *connectionParams, unsigned paramCount, RFC_ERROR_INFO *errorInfo)
	Registers a server connection at an SAP gateway. More...
DECL_EXP RFC_CONNECTION_HANDLE SAP_API	RfcStartServer (int argc, SAP_UC **argv, RFC_CONNECTION_PARAMETER const *connectionParams, unsigned paramCount, RFC_ERROR_INFO *errorInfo)
	Allows a program to be used as an RFC server which is started by the backend on demand. More...
DECL_EXP RFC_RC SAP_API	RfcCloseConnection (RFC_CONNECTION_HANDLE rfcHandle, RFC_ERROR_INFO *errorInfo)
	Closes an RFC connectionCan be used to close client connections as well as server connections, when they are no longer needed. More...
DECL_EXP RFC_RC SAP_API	RfcIsConnectionHandleValid (RFC_CONNECTION_HANDLE rfcHandle, int *isValid, RFC_ERROR_INFO *errorInfo)
	Checks an RFC connectionCan be used to check whether a client/server connection has already been closed, or whether the NW RFC library still "considers" the connection to be open. More...
DECL_EXP RFC_RC SAP_API	RfcCancel (RFC_CONNECTION_HANDLE rfcHandle, RFC_ERROR_INFO *errorInfo)
	Cancels the RFC call which is currently being called over the given RFC connection and closes the connectionCan be used only on an RFC client connection and needs to be called from a different thread than the one currently executing the RFC call. More...
DECL_EXP RFC_RC SAP_API	RfcResetServerContext (RFC_CONNECTION_HANDLE rfcHandle, RFC_ERROR_INFO *errorInfo)
	RFC_RC SAP_API RfcResetServerContextResets the SAP server context ("user context / ABAP session context") associated with the given client connection, but does not close the connection. More...
DECL_EXP RFC_RC SAP_API	RfcPing (RFC_CONNECTION_HANDLE rfcHandle, RFC_ERROR_INFO *errorInfo)
	Ping the remote communication partner through the passed connection handle. More...
DECL_EXP RFC_RC SAP_API	RfcGetConnectionAttributes (RFC_CONNECTION_HANDLE rfcHandle, RFC_ATTRIBUTES *attr, RFC_ERROR_INFO *errorInfo)
	Returns details about the current client or server connection. More...
DECL_EXP RFC_RC SAP_API	RfcGetServerContext (RFC_CONNECTION_HANDLE rfcHandle, RFC_SERVER_CONTEXT *context, RFC_ERROR_INFO *errorInfo)
	Inside a server function, returns details about the current execution context. More...
DECL_EXP RFC_RC SAP_API	RfcGetSapRouter (RFC_CONNECTION_HANDLE rfcHandle, SAP_UC *sapRouter, unsigned *length, RFC_ERROR_INFO *errorInfo)
	Gets the SAPRouter, if any. More...
DECL_EXP RFC_RC SAP_API	RfcGetPartnerExternalIP (RFC_CONNECTION_HANDLE rfcHandle, SAP_UC *partnerExternalIP, unsigned *length, RFC_ERROR_INFO *errorInfo)
	Gets the external IP address of the communication partner. More...
DECL_EXP RFC_RC SAP_API	RfcGetLocalAddress (RFC_CONNECTION_HANDLE rfcHandle, SAP_UC *localAddress, unsigned *length, unsigned *localPort, RFC_ERROR_INFO *errorInfo)
	Gets the IP address of the local network interface used by this connection. More...
DECL_EXP RFC_RC SAP_API	RfcGetPartnerSSOTicket (RFC_CONNECTION_HANDLE rfcHandle, SAP_UC *ssoTicket, unsigned *length, RFC_ERROR_INFO *errorInfo)
	Gets the partner's SSO2 ticket, if any. More...
DECL_EXP RFC_RC SAP_API	RfcGetPartnerSNCName (RFC_CONNECTION_HANDLE rfcHandle, SAP_UC *sncName, unsigned length, RFC_ERROR_INFO *errorInfo)
	Gets the partner's SNC name, if any. More...
DECL_EXP RFC_RC SAP_API	RfcGetPartnerSNCKey (RFC_CONNECTION_HANDLE rfcHandle, SAP_RAW *sncKey, unsigned *length, RFC_ERROR_INFO *errorInfo)
	Gets partner's SNC key, if any. More...
DECL_EXP RFC_RC SAP_API	RfcSNCNameToKey (SAP_UC const *sncLib, SAP_UC const *sncName, SAP_RAW *sncKey, unsigned *keyLength, RFC_ERROR_INFO *errorInfo)
	Converts SNC name to SNC key. More...
DECL_EXP RFC_RC SAP_API	RfcSNCKeyToName (SAP_UC const *sncLib, SAP_RAW const *sncKey, unsigned keyLength, SAP_UC *sncName, unsigned nameLength, RFC_ERROR_INFO *errorInfo)
	Converts SNC key to SNC name. More...
DECL_EXP RFC_RC SAP_API	RfcListenAndDispatch (RFC_CONNECTION_HANDLE rfcHandle, int timeout, RFC_ERROR_INFO *errorInfo)
	Listens on a server connection handle and waits for incoming RFC calls from the R/3 system. More...
DECL_EXP RFC_RC SAP_API	RfcInvoke (RFC_CONNECTION_HANDLE rfcHandle, RFC_FUNCTION_HANDLE funcHandle, RFC_ERROR_INFO *errorInfo)
	Executes a function module in the backend system. More...

Detailed Description

Opening and closing client & server connections.

Enumeration Type Documentation

enum _RFC_CALL_TYPE

Used in RfcGetServerContext() for inquiring the type of an incoming function call from the backend.

Enumerator
RFC_SYNCHRONOUS	It's a standard synchronous RFC call.
RFC_TRANSACTIONAL	This function call is part of a transactional LUW (tRFC).
RFC_QUEUED	This function call is part of a queued LUW (qRFC).
RFC_BACKGROUND_UNIT	This function call is part of a background LUW (bgRFC).

Definition at line 345 of file sapnwrfc.h.

enum _RFC_PROTOCOL_TYPE

Used in state information in order to indicate the different types of RFC programs, RFC Server types, etc.

Enumerator
RFC_UNKOWN	Unspecified.
RFC_CLIENT	RFC Client.
RFC_STARTED_SERVER	Started RFC Server.
RFC_REGISTERED_SERVER	Registered RFC Server.
RFC_MULTI_COUNT_REGISTERED_SERVER	Multi-count registered RFC Server.
RFC_TCP_SOCKET_CLIENT	TCP Client.
RFC_TCP_SOCKET_SERVER	TCP Server.
RFC_WEBSOCKET_CLIENT	Websocket RFC Client.
RFC_WEBSOCKET_SERVER	Websocket RFC Server.
RFC_PROXY_WEBSOCKET_CLIENT	Websocket RFC Client.

Definition at line 492 of file sapnwrfc.h.

Function Documentation

DECL_EXP RFC_RC SAP_API RfcCancel	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_ERROR_INFO *	errorInfo
	)

Cancels the RFC call which is currently being called over the given RFC connection and closes the connectionCan be used only on an RFC client connection and needs to be called from a different thread than the one currently executing the RFC call.

Parameters

[in]	rfcHandle	RFC client connection which is currently blocked in RfcInvoke().
[out]	*errorInfo	Error details in case canceling fails. (Can usually be ignored...)

Returns

RFC_OK, if cancel was requested; RFC_ILLEGAL_STATE, if the connection is currently not in a call; or RFC_NOT_SUPPORTED, if the handle is a server handle.

DECL_EXP RFC_RC SAP_API RfcCloseConnection	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_ERROR_INFO *	errorInfo
	)

Closes an RFC connectionCan be used to close client connections as well as server connections, when they are no longer needed.

Parameters

[in]	rfcHandle	Connection to be closed
[out]	*errorInfo	Error details in case closing the connection fails. (Can usually be ignored...)

Returns

RFC_RC

DECL_EXP RFC_RC SAP_API RfcFreeSaplogonEntries	(	SAP_UC ***	saplogonIDList,
		unsigned *	numSaplogonIDs,
		RFC_ERROR_INFO *	errorInfo
	)

Frees a list of SAPLogon IDs obtained from RfcGetSaplogonEntries().

When you no longer need the SAPLogon IDs obtained from RfcGetSaplogonEntries(), you should call this function with the same arguments that got filled by RfcGetSaplogonEntries(). This will free any internal memory occupied by the list of SAPLogon IDs.

Parameters

[in,out]	***saplogonIDList	Points to an SAP_UC* array that was previously filled by RfcGetSaplogonEntries(). Will be set to NULL.
[in,out]	*numSaplogonIDs	Points to the length of the SAPLogon ID list. Will be set to 0.
[out]	*errorInfo	Returns more error details, if something goes wrong.

Returns

Nothing that can go wrong here really.

DECL_EXP RFC_RC SAP_API RfcFreeSaplogonEntry	(	RFC_CONNECTION_PARAMETER **	entryParameters,
		unsigned *	numParameters,
		RFC_ERROR_INFO *	errorInfo
	)

Frees an array of connection parameters obtained from RfcGetSaplogonEntry().

When you no longer need the connection parameters obtained from RfcGetSaplogonEntries(), you should call this function with the same arguments that got filled by RfcGetSaplogonEntry(). This will free any internal memory occupied by the array of parameters.

Parameters

[in,out]	**entryParameters	Points to an RFC_CONNECTION_PARAMETER array that was previously filled by RfcGetSaplogonEntry(). Will be set to NULL.
[in,out]	*numParameters	Points to the length of the connection parameter array. Will be set to 0.
[out]	*errorInfo	Returns more error details, if something goes wrong.

Returns

Nothing that can go wrong here really.

DECL_EXP RFC_RC SAP_API RfcGetConnectionAttributes	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_ATTRIBUTES *	attr,
		RFC_ERROR_INFO *	errorInfo
	)

Returns details about the current client or server connection.

Consider that in case you are a server and call RfcListenAndDispatch(), the partner fields of the attributes will be cleared. The reason is, although we might be only connected to a gateway of one application server, the function module can be also called from the other application servers of the system if configured accordingly in the SM59 destination.

I.e. expect only valid partner information from within a function module. Outside of the function module, e.g. in the loop where RfcListenAndDispatch is called, you will get cleared partner information in most of the cases except case RFC_OK, which means that you were just called by an application server.

See documentation of RFC_ATTRIBUTES.

Parameters

[in]	rfcHandle	RFC connection
[out]	*attr	Information about the current connection and the communication partner on the other side.
[out]	*errorInfo	Additional error information (e.g. connection already closed).

Returns

RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetLocalAddress	(	RFC_CONNECTION_HANDLE	rfcHandle,
		SAP_UC *	localAddress,
		unsigned *	length,
		unsigned *	localPort,
		RFC_ERROR_INFO *	errorInfo
	)

Gets the IP address of the local network interface used by this connection.

On servers with multiple network interfaces, it may be useful to know, via which interface the current connection has been established.

Parameters

[in]	rfcHandle	RFC connection
[out]	*localAddress	Pre-allocated buffer. If you use a buffer of length at least 46, it will always be sufficient, even in case of IPv6 addresses.
[in,out]	*length	Needs to be filled with the buffer length of partnerExternalIP. The return value will be the string length of the returned external IP (if buffer was large enough) or the required buffer size (if RFC_BUFFER_TOO_SMALL). In the first case, the length value will be the string length without the terminating zero, in the second case it will be the required buffer size including the terminating zero.
[out]	*localPort	The local port used for the network connection.
[out]	*errorInfo	More error details in case something goes wrong.

Returns

RFC_BUFFER_TOO_SMALL, if the provided partnerExternalIP buffer was too small. RFC_INVALID_HANDLE, if the given rfcHandle is not connected. RFC_INVALID_PARAMETER, if one of the input values is invalid. RFC_EXTERNAL_FAILURE, if a network level error occurs. RFC_OK otherwise.

DECL_EXP RFC_RC SAP_API RfcGetPartnerExternalIP	(	RFC_CONNECTION_HANDLE	rfcHandle,
		SAP_UC *	partnerExternalIP,
		unsigned *	length,
		RFC_ERROR_INFO *	errorInfo
	)

Gets the external IP address of the communication partner.

In scenarios where NAT (Network Address Translation) is performed between the LAN segment, where the external RFC program is running, and the LAN segment, where the backend system is running, the RFC_ATTRIBUTES (members "partnerHost", "partnerIP" or "partnerIPv6") will always contain the hostname/address returned by the backend system, which is the address as it is known inside the internal LAN segment. However, this address is usually unusable/invalid inside the external LAN segment. External programs that need a valid "external" IP address of the current communication partner, can use this API to obtain it. If no NAT is used in the current scenario, the value returned by this API will be equal to partnerIP/partnerIPv6 from the RFC_ATTRIBUTES.

Parameters

[in]	rfcHandle	RFC connection
[out]	*partnerExternalIP	Pre-allocated buffer
[in,out]	*length	Needs to be filled with the buffer length of partnerExternalIP. The return value will be the string length of the returned external IP (if buffer was large enough) or the required buffer size (if RFC_BUFFER_TOO_SMALL). In the first case, the length value will be the string length without the terminating zero, in the second case it will be the required buffer size including the terminating zero.
[out]	*errorInfo	More error details in case something goes wrong.

Returns

RFC_BUFFER_TOO_SMALL, if the provided partnerExternalIP buffer was too small. RFC_INVALID_HANDLE, if the given rfcHandle is not connected. RFC_INVALID_PARAMETER, if one of the input values is invalid. RFC_OK otherwise.

DECL_EXP RFC_RC SAP_API RfcGetPartnerSNCKey	(	RFC_CONNECTION_HANDLE	rfcHandle,
		SAP_RAW *	sncKey,
		unsigned *	length,
		RFC_ERROR_INFO *	errorInfo
	)

Gets partner's SNC key, if any.

Parameters

[in]	rfcHandle	RFC server connection. If this function is executed on a client connection, RFC_ILLEGAL_STATE will be returned.
[out]	*sncKey	Pre-allocated buffer, which will receive the backend user's SNC key.
[in,out]	*length	Needs to be filled with the buffer length of ssoTicket. The return value will be the byte length of the returned key (if buffer was large enough). Unfortunately in case of RFC_BUFFER_TOO_SMALL the required size is not returned by the GSS library. The maximum length of an SNC key is 1024.
[out]	*errorInfo	More error details in case SNC is not active.

Returns

RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetPartnerSNCName	(	RFC_CONNECTION_HANDLE	rfcHandle,
		SAP_UC *	sncName,
		unsigned	length,
		RFC_ERROR_INFO *	errorInfo
	)

Gets the partner's SNC name, if any.

Parameters

[in]	rfcHandle	RFC server connection. If this function is executed on a client connection, RFC_ILLEGAL_STATE will be returned.
[out]	*sncName	Pre-allocated buffer, which will receive the backend user's SNC name (null-terminated string).
[in]	length	Size of the pre-allocated buffer. This information is coming from the GSS library, therefore unfortunately the feature of assigning the used/required length to an output parameter is not possible in this case. The maximum length of an SNC name is 256.
[out]	*errorInfo	More error details in case SNC is not active.

Returns

RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetPartnerSSOTicket	(	RFC_CONNECTION_HANDLE	rfcHandle,
		SAP_UC *	ssoTicket,
		unsigned *	length,
		RFC_ERROR_INFO *	errorInfo
	)

Gets the partner's SSO2 ticket, if any.

Can be used in two cases: call it inside the implementation of a server function and pass the server connection as rfcHandle, if you want to obtain the ticket sent from the ABAP side. For this to work, one of the flags "Send Logon Ticket" or "Send Assertion Ticket" (or similar) needs to be activated in the definition of the corresponding RFC destination in SM59. Or call it after RfcOpenConnection() and pass the client connection as rfcHandle, to obtain the ticket issued for the currrently logged in user. For this to work, the connection must be opened with parameter GETSSO2=1 and the profile parameter login/create_sso2_ticket must be set to a value different from "0" in the backend.

Parameters

[in]	rfcHandle	RFC server connection
[out]	*ssoTicket	Pre-allocated buffer, which will receive the backend user's SSO2 ticket (signed user information in base64 format)
[in,out]	*length	Needs to be filled with the buffer length of ssoTicket. The return value will be the string length of the returned ticket (if buffer was large enough) or the required buffer size (if RFC_BUFFER_TOO_SMALL). In the first case, the length value will be the string length without the terminating zero, in the second case it will be the required buffer size including the terminating zero.
[out]	*errorInfo	More error details in case there is no ticket.

Returns

RFC_RC

Warning

DECL_EXP RFC_RC SAP_API RfcGetSaplogonEntries	(	SAP_UC ***	saplogonIDList,
		unsigned *	numSaplogonIDs,
		RFC_ERROR_INFO *	errorInfo
	)

Returns a list of names of all SAP Systems maintained in SAPLogon (saplogon.ini or SAPUILandscape.xml).

On Windows systems, where SAPLogon is installed, the logon parameters defined in saplogon.ini can be used for opening connections to those backend systems. This routine retrieves a list of all available SAP systems. Each key in the list can be used as a value for RFC_CONNECTION_PARAMETER.value, where RFC_CONNECTION_PARAMETER.name = "SAPLOGON_ID". For more information see the documentation of the SAPLOGON_ID parameter in the sample sapnwrfc.ini file.

If the API returns successfully, you should call RfcFreeSaplogonEntries() with the same inputs, once you no longer need the SAPLogon IDs, so that the memory occupied by them can be cleaned up.

Sample code illustrating how to use the SAPLogon IDs:

SAP_UC** logonIDList;
unsigned numEntries;
RfcGetSaplogonEntries(&logonIDList, &numEntries, &errorInfo);

if (errorInfo.code == RFC_OK){
      for (unsigned i=0; i<numEntries; ++i) printfU(cU("%s\n"), logonIDList[i]);
}
RfcFreeSaplogonEntries(&logonIDList, &numEntries, &errorInfo);

Parameters

[out]	***saplogonIDList	Receives a pointer to a SAP_UC* array containing the SAPLogon IDs.
[out]	*numSaplogonIDs	Will be filled with the number of SAPLogon IDs in the list.
[out]	*errorInfo	Returns more error details, if the list of saplogon.ini keys could not be retrieved.

Returns

RFC_MEMORY_INSUFFICIENT, if unable to malloc memory for the ID list; RFC_NOT_FOUND, if saplogon.ini could not be found on that system or is empty.

DECL_EXP RFC_RC SAP_API RfcGetSaplogonEntry	(	SAP_UC *	saplogonID,
		RFC_CONNECTION_PARAMETER **	entryParameters,
		unsigned *	numParameters,
		RFC_ERROR_INFO *	errorInfo
	)

Retrieves all connection parameters corresponding to the given ID from the saplogon.ini or SAPUILandscape.xml file.

The ID needs to be one of those returned by RfcGetSaplogonEntries(). It is the same as can also be used as connection parameter SAPLOGON_ID.

Parameters

[in]	*saplogonID	A SAPLogon ID uniquely identifying a certain saplogon.ini or SAPUILandscape.xml entry.
[out]	**entryParameters	Receives a pointer to a RFC_CONNECTION_PARAMETER array containing the parameters of the given SAPLogon ID.
[out]	*numParameters	Will be filled with the number of connection parameters in the array.
[out]	*errorInfo	Returns more error details, if something goes wrong, e.g. out of memory or SAPLogon ID cannot be found.

Returns

Nothing that can go wrong here really.

DECL_EXP RFC_RC SAP_API RfcGetSapRouter	(	RFC_CONNECTION_HANDLE	rfcHandle,
		SAP_UC *	sapRouter,
		unsigned *	length,
		RFC_ERROR_INFO *	errorInfo
	)

Gets the SAPRouter, if any.

Parameters

[in]	rfcHandle	RFC connection
[out]	*sapRouter	Pre-allocated buffer
[in,out]	*length	Needs to be filled with the buffer length of sapRouter. The return value will be the string length of the returned sapRouter (if buffer was large enough) or the required buffer size (if RFC_BUFFER_TOO_SMALL). In the first case, the length value will be the string length without the terminating zero, in the second case it will be the required buffer size including the terminating zero.
[out]	*errorInfo	More error details in case something goes wrong.

Returns

RFC_BUFFER_TOO_SMALL, if the provided sapRouter buffer was too small. RFC_OK otherwise.

DECL_EXP RFC_RC SAP_API RfcGetServerContext	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_SERVER_CONTEXT *	context,
		RFC_ERROR_INFO *	errorInfo
	)

Inside a server function, returns details about the current execution context.

See documentation of RFC_SERVER_CONTEXT.

Parameters

[in]	rfcHandle	RFC server connection
[out]	*context	Information about the current server execution context.
[out]	*errorInfo	Additional error information (e.g. connection is not a server connection).

Returns

RFC_RC

DECL_EXP RFC_RC SAP_API RfcInvoke	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_FUNCTION_HANDLE	funcHandle,
		RFC_ERROR_INFO *	errorInfo
	)

Executes a function module in the backend system.

The return codes have the following meaning:

• RFC_OK
  The function call was executed successfully.
• RFC_ABAP_EXCEPTION
  The function call was executed and ended with a defined ABAP Exception. The key of the exception can be obtained from errorInfo->key.

In the above two cases "rfcHandle" is still open and can be used to execute further function call.

• RFC_ABAP_MESSAGE
  The function call was started to be processed, but was aborted with an ABAP Message. The message parameters can be obtained from errorInfo->abapMsgClass, errorInfo->abapMsgType, errorInfo->abapMsgNumber, errorInfo->abapMsgV1, ..., errorInfo->abapMsgV4.
• RFC_ABAP_RUNTIME_FAILURE
  The function call was started to be processed, but was aborted with a SYSTEM_FAILURE (e.g division by zero, unhandled exception, etc in the backend system). Details can be obtained from errorInfo->message.
• RFC_COMMUNICATION_FAILURE
  The connection broke down while processing the function call. Details can be obtained from errorInfo->message.

In these three cases the connection has been closed, so the "rfcHandle" needs to be refreshed via RfcOpenConnection.

• RFC_INVALID_HANDLE
  "rfcHandle" is invalid or points to a connection that has already been closed.

Parameters

[in]	rfcHandle	Client connection over which to execute the function module.
[in,out]	funcHandle	Data container containing the input data for the function module. RfcInvoke() will write the FM's output data into this container.
[out]	*errorInfo	Additional error information.

Returns

RFC_RC

DECL_EXP RFC_RC SAP_API RfcIsConnectionHandleValid	(	RFC_CONNECTION_HANDLE	rfcHandle,
		int *	isValid,
		RFC_ERROR_INFO *	errorInfo
	)

Checks an RFC connectionCan be used to check whether a client/server connection has already been closed, or whether the NW RFC library still "considers" the connection to be open.

Note that this does not guarantee that the connection is indeed still alive: A firewall may silently have closed the connection without notifying the endpoints. If you want to find out, whether the connection is still alive, you'll have to use the more expensive RfcPing().

Parameters

[in]	rfcHandle	Connection to be checked
[out]	*isValid	1, if the connection is still found in the internal connection management, 0 otherwise.
[out]	*errorInfo	Error details in case the connection is invalid.

Returns

RFC_RC

DECL_EXP RFC_RC SAP_API RfcListenAndDispatch	(	RFC_CONNECTION_HANDLE	rfcHandle,
		int	timeout,
		RFC_ERROR_INFO *	errorInfo
	)

Listens on a server connection handle and waits for incoming RFC calls from the R/3 system.

The mechanism for dispatching incoming function calls works as follows: First RfcListenAndDispatch() checks, whether for the current combination of R/3 SystemID and function module name a callback function has been installed via RfcInstallServerFunction(). If not, it checks, whether a callback function for SystemID=NULL has been installed via RfcInstallServerFunction().If not, it checks, whether a global callback function has been installed via RfcInstallGenericServerFunction().

If a callback function has been found, the RFC call will be dispatched to that function for processing, and RfcListenAndDispatch() returns the return code of the callback function. Otherwise RfcListenAndDispatch() returns a SYSTEM_FAILURE to the R/3 backend and the return code RFC_NOT_FOUND to the caller.

In general the return codes of RfcListenAndDispatch() have the following meaning:

• RFC_OK
  A function call was processed successfully.
• RFC_RETRY
  No function call came in within the specified timeout period. ("timeout" is given in seconds.)
• RFC_ABAP_EXCEPTION
  A function call was processed and ended with a defined ABAP Exception, which has been returned to the backend.

In the above three cases "rfcHandle" is still open and can be used to listen for the next request.

• RFC_ABAP_MESSAGE
  A function call was started to be processed, but was aborted with an ABAP A-, E- or X-Message. The message parameters have been returned to the backend (and can be evaluated there via the sy-msgid, sy-msgtype, sy-msgno, sy-msgv1, ..., sy-msgv4 parameters).
• RFC_EXTERNAL_FAILURE
  A function call was started to be processed, but was aborted with a "SYSTEM_FAILURE", which has been returned to the backend.
• RFC_COMMUNICATION_FAILURE
  The connection broke down while processing the function call. No response has been sent to the backend.
• RFC_CLOSED
  The connection has been closed by the backend side (SMGW, SM04). No response has been sent to the backend.
• RFC_NOT_FOUND
  No handler has been found for the current function module name. A SYSTEM_FAILURE has been returned to the R/3 backend.

In these five cases the connection has been closed, so the "rfcHandle" needs to be refreshed via RfcRegisterServer.

• RFC_INVALID_HANDLE
  "rfcHandle" is invalid or points to a connection that has already been closed.

Parameters

[in]	rfcHandle	Server connection on which to listen for incoming requests.
[in]	timeout	Number of seconds to wait for an incoming request.
[out]	*errorInfo	Additional error information.

Returns

RFC_RC

DECL_EXP RFC_CONNECTION_HANDLE SAP_API RfcOpenConnection	(	RFC_CONNECTION_PARAMETER const *	connectionParams,
		unsigned	paramCount,
		RFC_ERROR_INFO *	errorInfo
	)

Opens an RFC client connection for invoking ABAP function modules in an R/3 backend.

Opens a client connection to an SAP System. The connectionParams may contain the following name-value pairs:

• client, user, passwd, lang, trace

and additionally one of

1. Direct application server logon: ashost, sysnr.
2. Logon with load balancing: mshost, msserv, sysid, group.
   msserv is needed only, if the service of the message server is not defined as sapms<SYSID> in /etc/services.

When logging on with SNC, user&passwd are to be replaced by

• snc_qop, snc_myname, snc_partnername and optionally snc_lib.

(If snc_lib is not specified, the underlying SNC layer uses the "global" GSS library defined via environment variable SNC_LIB or SNC_LIB_64.)

When logging on with SSO Ticket, you can use mysapsso2 instead of user&passwd. The old SSO format (mysapsso) is no longer supported.

Alternatively the connection parameters can be defined in the config file sapnwrfc.ini. In this case you just pass the parameter dest=... and all parameters that are missing in the sapnwrfc.ini entry into RfcOpenConnection().

For a complete list of logon parameters to be used in connectionParams as well as in the sapnwrfc.ini file, see the sample sapnwrfc.ini file in the SDK's demo folder.

If the logon was ok, RfcOpenConnection() returns a client connection handle, which can be used in RfcInvoke(). Otherwise the return value is NULL and errorInfo contains a detailed error description. errorInfo->code will be one of:

• RFC_INVALID_PARAMETER One of the connectionParams was invalid
• RFC_COMMUNICATION_FAILURE Something is wrong with the network or network settings
• RFC_LOGON_FAILURE Invalid user/password/ticket/certificate
• RFC_ABAP_RUNTIME_FAILURE Something is wrong with the R/3 backend
• RFC_MEMORY_INSUFFICIENT A malloc failed when trying to allocate a temporary buffer

Parameters

[in]	*connectionParams	An array of RFC_CONNECTION_PARAMETERs with the names as described above and the values as necessary in your landscape.
[in]	paramCount	Number of parameters in the above array.
[out]	*errorInfo	Returns more error details, if the connect attempt fails.

Returns

A handle to an RFC client connection that can be used for invoking ABAP function modules in the backend.

DECL_EXP RFC_RC SAP_API RfcPing	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_ERROR_INFO *	errorInfo
	)

Ping the remote communication partner through the passed connection handle.

Sends a ping to the backend in order to check, whether the connection is still alive. Can be used on both, client connections as well as server connections.

Warning

Do not use inside a server function implementation.

Parameters

[in]	rfcHandle	The connection to check
[out]	*errorInfo	More error details in case the connection is broken.

Returns

RFC_RC

DECL_EXP RFC_CONNECTION_HANDLE SAP_API RfcRegisterServer	(	RFC_CONNECTION_PARAMETER const *	connectionParams,
		unsigned	paramCount,
		RFC_ERROR_INFO *	errorInfo
	)

Registers a server connection at an SAP gateway.

The connectionParams may contain the following name-value pairs:

• gwhost, gwserv, program_id, trace, and the parameters for SNC communication as in RfcOpenConnection().

Program_id corresponds to an RFC destination in SM59 of type "T" in registration mode.

For a complete list of logon parameters to be used in connectionParams as well as in the sapnwrfc.ini file, see the sample sapnwrfc.ini file in the SDK's demo folder.

If the connection registration was ok, RfcRegisterServer() returns a server connection handle, which can be used in RfcListenAndDispatch(). Otherwise the return value is NULL and errorInfo contains information similar to the RfcOpenConnection() case.

Parameters

[in]	*connectionParams	An array of RFC_CONNECTION_PARAMETERs with the names as described above and the values as necessary in your landscape.
[in]	paramCount	Number of parameters in the above array.
[out]	*errorInfo	Returns more error details, if the connect attempt fails.

Returns

A handle to an RFC server connection that can be used for listening for function module requests from the backend.

DECL_EXP RFC_RC SAP_API RfcResetServerContext	(	RFC_CONNECTION_HANDLE	rfcHandle,
		RFC_ERROR_INFO *	errorInfo
	)

RFC_RC SAP_API RfcResetServerContextResets the SAP server context ("user context / ABAP session context") associated with the given client connection, but does not close the connection.

Parameters

[in]	rfcHandle	The client connection, whose server context is to be reset.
[out]	*errorInfo	Error details in case resetting the server context fails. (Better close the connection in that case.)

Returns

RFC_RC

DECL_EXP RFC_RC SAP_API RfcSNCKeyToName	(	SAP_UC const *	sncLib,
		SAP_RAW const *	sncKey,
		unsigned	keyLength,
		SAP_UC *	sncName,
		unsigned	nameLength,
		RFC_ERROR_INFO *	errorInfo
	)

Converts SNC key to SNC name.

Parameters

[in]	*sncLib	Optional: file name of the GSS library to be used for the conversion. If not specified, the "global" GSS library (environment variable SNC_LIB or SNC_LIB_64) will be used.
[in]	*sncKey	SNC key to be converted.
[in]	keyLength	Byte length of the given SNC key
[out]	*sncName	Pre-allocated buffer, which will receive the corresponding (null-terminated) SNC name.
[in]	nameLength	Size of the given sncName buffer. (The maximum length of an SNC name is 256.)
[out]	*errorInfo	More error details in case something goes wrong.

Returns

RFC_RC

DECL_EXP RFC_RC SAP_API RfcSNCNameToKey	(	SAP_UC const *	sncLib,
		SAP_UC const *	sncName,
		SAP_RAW *	sncKey,
		unsigned *	keyLength,
		RFC_ERROR_INFO *	errorInfo
	)

Converts SNC name to SNC key.

Parameters

[in]	*sncLib	Optional: file name of the GSS library to be used for the conversion. If not specified, the "global" GSS library (environment variable SNC_LIB or SNC_LIB_64) will be used.
[in]	*sncName	Null-terminated SNC name to be converted.
[out]	*sncKey	Pre-allocated buffer, which will receive the corresponding SNC key.
[in,out]	*keyLength	Needs to be filled with the buffer length of sncKey. The return value will be byte length of the SNC key (if buffer was large enough). Unfortunately in case of RFC_BUFFER_TOO_SMALL the required size is not returned by the GSS library. The maximum length of an SNC key is 1024.
[out]	*errorInfo	More error details in case something goes wrong.

Returns

RFC_RC

DECL_EXP RFC_CONNECTION_HANDLE SAP_API RfcStartServer	(	int	argc,
		SAP_UC **	argv,
		RFC_CONNECTION_PARAMETER const *	connectionParams,
		unsigned	paramCount,
		RFC_ERROR_INFO *	errorInfo
	)

Allows a program to be used as an RFC server which is started by the backend on demand.

This API needs to be called, if the server program is to be started by the R/3 application server. (RFC destination in SM59 of type "T" in startup mode.) argc and argv are the inputs of the mainU function. The R/3 application server passes the correct command line to the program, when starting it up, so you only need to forward these two parameters to RfcStartServer(). connectionParams is optional and is only needed, if you want to add additional logon parameters to the ones coming from the command line, e.g for activating trace.

Like RfcRegisterServer(), the function returns a server connection handle that can be used in RfcListenAndDispatch(). The mechanism of this kind of RFC destination thus works as follows:

1. The R/3 application server opens a telnet connection to the host, where your server program is located, and starts the program with the necessary logon parameters. (Or creates a child process, if the startup method is "Start on application server".)
2. Your server program calls RfcStartServer, which opens an RFC connection back to the R/3 system.
3. The R/3 system then makes the function call over that RFC connection.

The main differences of "startup mode" compared to the "registration mode" are:

• Advantage: no logon parameters need to be maintained in the server program. (Unless you want to open an additional client connection for looking up function module metadata (RFC_FUNCTION_DESC_HANDLEs) in the R/3 DDIC.)
• Disadvantage: every single function call creates a new process and possibly a remote shell connection in addition to the actual RFC connection.

Parameters

[in]	argc	From mainU() (command line supplied by backend)
[in]	**argv	From mainU() (command line supplied by backend)
[in]	*connectionParams	May optionally contain additional logon parameters
[in]	paramCount	Length of the connection parameter array above
[out]	*errorInfo	Returns more error details, if the connect attempt fails.

Returns

A handle to an RFC server connection that can be used for listening for function module requests from the backend.