Functions: Handles & Sessions

Functions for creating and releasing a session or a handle.

eplCreateSession

EplSession
eplCreateSession ();

Function for creating a new session.

Return Description
EplSession Handle of the session if a session could be generated, otherwise EPL_ERROR.

eplDestroySession

EplHandle
eplDestroySession (EplSession session);

Function for releasing a session. All handles that are contained in the session are also released.

Return Description
EplHandle EPL_OK if the session could be released, otherwise EPL_ERROR.
Input Type Description
session EplSession Handle of the session to be released.

eplClearAllHandles

EplHandle
eplClearAllHandles(EplSession        session);

Function for releasing all handles in a session. In contrast to eplDestroySession, the session itself is not closed.

This function must not be used for a session that has been transferred by the system to a command or notification handler!

Return Description
EplHandle EPL_OK if the handles of the session could be released, otherwise EPL_ERROR.
Input Type Description
session EplSession Handle of the session whose handles are to be released.

eplCloseObject

EplHandle
eplCloseObject(EplSession        session,
                EplHandle        objHandle);

This function decrements the reference counter of the object to which the handle refers. If the reference counter equals zero, the object is finally released (in the case of iterators, commands, etc. - i.e. whenever an object was created with the handle). Please note that eplCloseObject should not be used for handles provided by an iterator. However, cloned handles should be closed after having closed the iterator.

Return Description
EplHandle EPL_OK if the handle could be released, otherwise EPL_ERROR.
Input Type Description
session EplSession Handle of the session in which the object handle was created.
objHandle EplHandle Handle of the object

eplCloneHandle

EplHandle
eplCloneHandle(EplSession        session,
               EplHandle        objHandle);

The reference counter of the handle is incremented.

This function is, e.g., required for the following scenario:

In order for the handle to be returned, its reference counter must be incremented first. If this is not done, the handle is released when closing the iterator so that it is not valid any more!

Return Description
EplHandle The handle is returned if the reference counter could be incremented, otherwise EPL_ERROR.
Input Type Description
session EplSession Handle of the session in which the object handle was created.
objHandle EplHandle Handle of the object to be incremented.

eplGetType

EplHandle
eplGetType(EplSession    session,
           EplHandle        objHandle);

Function for determining the type of a handle. The type is returned as return value and corresponds to the EplObjTypes from the EplanApiObjTypes.h file.

Return Description
EplHandle Type of the handle or EPL_ERROR if an invalid handle or an invalid session was transferred.
Input Type Description
session EplSession Handle of the session in which the object handle was created.
objHandle EplHandle Handle of the object whose type is to be queried.