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:
- A function is to be written which will return a handle to a certain page.
- For this purpose, the function creates an iterator for pages, searches the page, and returns the handle of the page once the iterator has been closed again (otherwise, there is a memory leak).
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.
|