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

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_SERVER_HANDLE
	Handle to an RFC Server, which can potentially reference multiple parallel listening server sessions. More...

struct	_RFC_SERVER_ATTRIBUTES
	Information about an RFC Server returned by RfcGetServerAttributes(). More...

struct	_RFC_SERVER_MONITOR_DATA
	Allows to retrieve monitoring information about all busy or idle connections of an RFC Server via RfcGetServerConnectionMonitorData(). 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 }
	Used in state information in order to indicate the different types of RFC programs, RFC Server types, etc. More...

enum	_RFC_SERVER_STATE { RFC_SERVER_INITIAL, RFC_SERVER_STARTING, RFC_SERVER_RUNNING, RFC_SERVER_BROKEN, RFC_SERVER_STOPPING, RFC_SERVER_STOPPED }
	Used in state information in order to indicate the current state of an RFC Server. 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). 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_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	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...

DECL_EXP RFC_SERVER_HANDLE SAP_API	RfcCreateServer (RFC_CONNECTION_PARAMETER const connectionParams, unsigned paramCount, RFC_ERROR_INFO errorInfo)
	This function can be used to start "automatic" servers as they are known from JCo and NCo. More...

DECL_EXP RFC_RC SAP_API	RfcDestroyServer (RFC_SERVER_HANDLE serverHandle, RFC_ERROR_INFO *errorInfo)
	Cleans up and destroys an automatic server object, once you are done with it. More...

DECL_EXP RFC_RC SAP_API	RfcLaunchServer (RFC_SERVER_HANDLE serverHandle, RFC_ERROR_INFO *errorInfo)
	Starts up an automatic server, so that it starts waiting for incoming requests and processes them. More...

DECL_EXP RFC_RC SAP_API	RfcShutdownServer (RFC_SERVER_HANDLE serverHandle, unsigned timeout, RFC_ERROR_INFO *errorInfo)
	Stops an automatic server, so that it no longer accepts incoming requests. More...

DECL_EXP RFC_RC SAP_API	RfcGetServerAttributes (RFC_SERVER_HANDLE serverHandle, RFC_SERVER_ATTRIBUTES serverAttributes, RFC_ERROR_INFO errorInfo)
	Retrieves detailed information about a multi-count Registered Server or a TCP Socket Server. More...

DECL_EXP RFC_RC SAP_API	RfcGetServerConnectionMonitorData (RFC_SERVER_HANDLE serverHandle, unsigned numberOfConnections, RFC_SERVER_MONITOR_DATA connectionData, RFC_ERROR_INFO errorInfo)
	Retrieves detailed information about all clients currently connected to a multi-count Registered Server or a TCP Socket Server. More...

DECL_EXP RFC_RC SAP_API	RfcDestroyServerConnectionMonitorData (unsigned numberOfConnections, RFC_SERVER_MONITOR_DATA connectionData, RFC_ERROR_INFO errorInfo)
	Releases all internal memory hold by monitor data object. More...

DECL_EXP RFC_RC SAP_API	RfcAddServerErrorListener (RFC_SERVER_HANDLE serverHandle, RFC_SERVER_ERROR_LISTENER errorListener, RFC_ERROR_INFO *errorInfo)
	Adds an error listener to this server. More...

DECL_EXP RFC_RC SAP_API	RfcAddServerStateChangedListener (RFC_SERVER_HANDLE serverHandle, RFC_SERVER_STATE_CHANGE_LISTENER stateChangeListener, RFC_ERROR_INFO *errorInfo)
	Adds a state change listener to this server. More...

DECL_EXP RFC_RC SAP_API	RfcSetServerStateful (RFC_CONNECTION_HANDLE connectionHandle, unsigned isStateful, RFC_ERROR_INFO *errorInfo)
	Sets this server's operation mode to statefull or stateless. 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 327 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.

Definition at line 431 of file sapnwrfc.h.

enum _RFC_SERVER_STATE

Used in state information in order to indicate the current state of an RFC Server.

Enumerator
RFC_SERVER_INITIAL	The server object has been created, but nothing has been done with it yet.
RFC_SERVER_STARTING	The server has been started, but startup is not yet complete and the server is not yet able to receive/serve requests. Should quickly switch to ALIVE or DEAD.
RFC_SERVER_RUNNING	Means at least one registration is still able to accept request from the gateway (in case of Registered Server), or that the server port is open and listening (in case of TCP Socket Server).
RFC_SERVER_BROKEN	Means that all registrations are dead, e.g. because of gateway being down (in case of Registered Server), or that for some reason server port could not be opened (in case of TCP Socket Server).
RFC_SERVER_STOPPING	The server has been stopped via RfcShutdownServer() (with a timeout > 0) and is still busy processing ongoing requests. It is however no longer accepting new requests. Should switch to STOPPED, once the ongoing requests are finished.
RFC_SERVER_STOPPED	The server has been stopped via RfcShutdownServer() and is currently not processing nor accepting any requests. The object, however, is still valid and can be started again anytime with RfcLaunchServer().

Definition at line 446 of file sapnwrfc.h.

Function Documentation

DECL_EXP RFC_RC SAP_API RfcAddServerErrorListener	(	RFC_SERVER_HANDLE	serverHandle,
		RFC_SERVER_ERROR_LISTENER	errorListener,
		RFC_ERROR_INFO *	errorInfo
	)

Adds an error listener to this server.

An error listener is a callback function of type RFC_SERVER_ERROR_LISTENER. The server will execute this function, whenever a severe technical error happens outside the processing of function modules, e.g. network problems with the gateway or with the connected clients.

Parameters

[in]	serverHandle	A handle to the server object.
[in]	errorListener	Function pointer to a callback function receiving error notifications.
[out]	*errorInfo	Additional error information in case adding the error listener fails, e.g. invalid handle.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcAddServerStateChangedListener	(	RFC_SERVER_HANDLE	serverHandle,
		RFC_SERVER_STATE_CHANGE_LISTENER	stateChangeListener,
		RFC_ERROR_INFO *	errorInfo
	)

Adds a state change listener to this server.

A state change listener is a callback function of type RFC_SERVER_STATE_CHANGE_LISTENER. The server will execute this function, whenever the server's state changes, e.g. from STARTED to ALIVE, or from ALIVE to STOPPING.

Parameters

[in]	serverHandle	A handle to the server object.
[in]	stateChangeListener	Function pointer to a callback function receiving state change notifications.
[out]	*errorInfo	Additional error information in case adding the state change listener fails, e.g. invalid handle.

Returns: RFC_RC

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_SERVER_HANDLE SAP_API RfcCreateServer	(	RFC_CONNECTION_PARAMETER const *	connectionParams,
		unsigned	paramCount,
		RFC_ERROR_INFO *	errorInfo
	)

This function can be used to start "automatic" servers as they are known from JCo and NCo.

In contrast to RfcRegisterServer(), which registers one single server connection at a SAP gateway, RfcCreateServer() can be used to create a "JCo-like" server object that manages multiple server connections in parallel, that takes care of automatically re-registering a connection in case it gets broken by network problems, etc. and that takes care of the dispatch-loop internally, so that application programmers no longer need to implement that error-prone task themselves. This means, you no longer need to use RfcListenAndDispatch() and no longer need to worry about creating multiple threads with such a listen- and dispatch-loop, if you want to process multiple parallel requests. All you need to do is starting an RFC_SERVER_HANDLE with RfcLaunchServer(), and it will listen for incoming requests on n parallel threads (as given by the parameter REG_COUNT).

In addition, you can start not only a usual registered Server that registers at an RFC gateway, but also a standalone Server that listens for requests on a network port and can be accessed by both, SAP systems and other external C-, Java- or .NET-based RFC client programs. Which kind of server is started, depends on the connection parameters:

Registered Server: Here you need to supply the standard parameters you would also use with RfcRegisterServer(). E.g. GWHOST, GWSERV and PROGRAM_ID, followed potentially by parameters for SNC, Trace, SAPRouter, etc. In addition you can supply the parameters REG_COUNT and MAX_REG_COUNT, if you want to process multiple requests in parallel (multiple gateway registrations). MAX_REG_COUNT is needed only for "stateful" RFC servers (see the sample sapnwrfc.ini for details). Alternatively to registering at only one fixed gateway, you can also provide parameters for "group registration". Then the server will register REG_COUNT connections at every gateway of the given logon group. Again see chapter 3 in the sapnwrfc.ini file.

For all types of servers you need to specify the parameter SERVER_NAME. This is a freely choosable name used for monitoring purposes.

After a server object has been created, it can be started and stopped any number of times via RfcLaunchServer() and RfcShutdownServer(). When the server is no longer needed, it must be cleaned up with RfcDestroyServer().

Parameters

[in]	*connectionParams	Array of network parameters needed for starting the server.
[out]	paramCount	Number of elements contained in the RFC_CONNECTION_PARAMETER array.
[out]	*errorInfo	Additional error information in case the server object could not be created (e.g. invalid parameters or insufficient memory).

Returns: A handle to the created server object.

DECL_EXP RFC_RC SAP_API RfcDestroyServer	(	RFC_SERVER_HANDLE	serverHandle,
		RFC_ERROR_INFO *	errorInfo
	)

Cleans up and destroys an automatic server object, once you are done with it.

Any internal resources of this server object are released. Therefore make sure not to use the RFC_SERVER_HANDLE in any further API calls (RfcLaunchServer(), RfcShutdownServer(), etc), after you have destroyed it.

Parameters

[in]	serverHandle	A handle to the server object.
[out]	*errorInfo	Not much that can go wrong here.

Returns: RFC_OK

DECL_EXP RFC_RC SAP_API RfcDestroyServerConnectionMonitorData	(	unsigned	numberOfConnections,
		RFC_SERVER_MONITOR_DATA *	connectionData,
		RFC_ERROR_INFO *	errorInfo
	)

Releases all internal memory hold by monitor data object.

Use this to free the data obtained from RfcGetServerConnectionMonitorData() once you no longer need it.

Parameters

[in]	numberOfConnections	Number of elements in the connectionData array.
[in]	connectionData	Array of connection data objects to be cleaned up.
[out]	*errorInfo	Can't go wrong...

Returns: RFC_OK

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 a 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 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 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 only with a server connection inside the implementation of a server function.

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).
[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).

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 RfcGetServerAttributes	(	RFC_SERVER_HANDLE	serverHandle,
		RFC_SERVER_ATTRIBUTES *	serverAttributes,
		RFC_ERROR_INFO *	errorInfo
	)

Retrieves detailed information about a multi-count Registered Server or a TCP Socket Server.

See RFC_SERVER_ATTRIBUTES for more details.

Parameters

[in]	serverHandle	A handle to the server object.
[out]	*serverAttributes	Is filled with state information, number of busy connections, etc.
[out]	*errorInfo	Not much can go wrong here, except an invalid handle.

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcGetServerConnectionMonitorData	(	RFC_SERVER_HANDLE	serverHandle,
		unsigned *	numberOfConnections,
		RFC_SERVER_MONITOR_DATA **	connectionData,
		RFC_ERROR_INFO *	errorInfo
	)

Retrieves detailed information about all clients currently connected to a multi-count Registered Server or a TCP Socket Server.

For every connected client you get its connection attributes (hostname, SID, user, client) as well as the current function module name, if the connection is busy, or the last activity time, if it is idle. Make sure to release the memory again with RfcDestroyServerConnectionMonitorData(), after you are done with it.

Parameters

[in]	serverHandle	A handle to the server object.
[out]	*numberOfConnections	Number of client connections currently connected to this server.
[out]	**connectionData	An array of monitor data structs, one for each client connection.
[out]	*errorInfo	Not much can go wrong here, except an invalid handle or out of memory.

Returns: RFC_RC

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 RfcLaunchServer	(	RFC_SERVER_HANDLE	serverHandle,
		RFC_ERROR_INFO *	errorInfo
	)

Starts up an automatic server, so that it starts waiting for incoming requests and processes them.

Parameters

[in]	serverHandle	A handle to the server object.
[out]	*errorInfo	Additional error information in case starting the server fails.

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

Direct application server logon: ashost, sysnr.
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 RfcSetServerStateful	(	RFC_CONNECTION_HANDLE	connectionHandle,
		unsigned	isStateful,
		RFC_ERROR_INFO *	errorInfo
	)

Sets this server's operation mode to statefull or stateless.

When a server operates in stateless mode, which is the default, it does not keep state information inbetween several RFC requests on the same connection. By setting it to stateful, you can change that so that all requests on one connection run inside one single "user session".

Parameters

[in]	connectionHandle	A handle to the current client connection. Use the one that gets passed to you in your RFC_SERVER_FUNCTION implementation.
[in]	isStateful	Specifies whether the server should operate in stateful mode ("1") or in stateless mode ("0").
[out]	*errorInfo	Additional error information in case changing the state fails, e.g. invalid handle..

Returns: RFC_RC

DECL_EXP RFC_RC SAP_API RfcShutdownServer	(	RFC_SERVER_HANDLE	serverHandle,
		unsigned	timeout,
		RFC_ERROR_INFO *	errorInfo
	)

Stops an automatic server, so that it no longer accepts incoming requests.

If timeout is set to 0, the server stops immediately, aborting any currently ongoing RFC requests. If you want to give any possibly ongoing requests a chance to complete, before stopping the server, provide a timeout > 0. RfcShutdownServer() will then block until all current requests are completed or the timeout period is over, whichever occurs first. In any case, the server will immediately stop accepting new requests as soon as you call this function.

If at a later point you want this server to resume listening for requests, you can start it again by calling RfcLaunchServer(). However, once you have cleaned up the server with RfcDestroyServer(), you must no longer attempt to use it in further RfcLaunchServer() (or other) calls.

Parameters

[in]	serverHandle	A handle to the server object.
[in]	timeout	Number of seconds to wait in order to give currently ongoing RFC requests time to complete.
[out]	*errorInfo	Not much that can go wrong here.

Returns: RFC_OK

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:

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".)
Your server program calls RfcStartServer, which opens an RFC connection back to the R/3 system.
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 a telnet 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.

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation