Client API

In the manual you will find detailed information about syntax, parameters and examples, please refer to it.

Administrative functions

These functions allow controlling the behavior a Client Object.

Function	Purpose
Cli_Create	Creates a Client Object.
Cli_Destroy	Destroys a Client Object.
Cli_SetConnectionType	Set the connection type (PG/OP/S7 Basic)
Cli_SetConnectionParams	Sets IP, Local and Remote TSAP
Cli_ConnectTo	Connects a Client Object to a PLC.
Cli_Connect	Connects a Client Object to a PLC with implicit parameters.
Cli_Disconnect	Disconnects a Client.
Cli_GetParam	Reads an internal Client parameter.
Cli_SetParam	Writes an internal Client Parameter.

Data I/O functions

These functions allow the Client to exchange data with a PLC.

Function	Purpose
Cli_ReadArea	Reads a data area from a PLC.
Cli_WriteArea	Writes a data area into a PLC.
Cli_DBRead	Reads a part of a DB from a PLC.
Cli_DBWrite	Writes a part of a DB into a PLC.
Cli_ABRead	Reads a part of IPU area from a PLC.
Cli_ABWrite	Writes a part of IPU area into a PLC.
Cli_EBRead	Reads a part of IPI area from a PLC.
Cli_EBWrite	Writes a part of IPI area into a PLC.
Cli_MBRead	Reads a part of Merkers area from a PLC.
Cli_MBWrite	Writes a part of Merkers area into a PLC.
Cli_TMRead	Reads timers from a PLC.
Cli_TMWrite	Write timers into a PLC.
Cli_CTRead	Reads counters from a PLC.
Cli_CTWrite	Write counters into a PLC.
Cli_ReadMultiVars	Reads different kind of variables from a PLC simultaneously.
Cli_WriteMultiVars	Writes different kind of variables into a PLC simultaneously.

Directory functions

These functions give you detailed information about the blocks present in a PLC.

Function	Purpose
Cli_ListBlocks	Returns the AG blocks amount divided by type.
Cli_ListBlocksOfType	Returns the AG blocks list of a given type.
Cli_GetAgBlockInfo	Returns detailed information about a block present in AG.
Cli_GetPgBlockInfo	Returns detailed information about a block loaded in memory.

Block oriented functions

These functions allow you to move blocks from/to the PLC and delete them.

AG Block Structure

A block (OB, FB, DB , etc.) in AG consists of:

· A Header containing main block info such as MC7Size, date and time etc.

· A Body containing the data.

· A Footer containing info about data struct such as number and type of elements of a DB. Additional block info such as author, family etc...

Block Header Main info		Cli_FullUpload
Block Body	Cli_Upload
Block Footer Struct Info

With these functions we can upload a block from AG in two ways : fully or data only depending on our needed, using  Cli_FullUpload() or Cli_Upload(). (1)

For the blocks downloading, however,  there are some limitations:

1. Only full blocks can be downloaded  into AG via Cli_Download().

2. A modified block, i.e. a block to which we have made changes to the body area, could be refused by the CPU.

Upload, download and deletion are subject to the security level set.

See Security functions for more info.

(1) S7 Protocol itself, only provides full upload, Snap7Client internally extracts the data body into Cli_Upload.

Function	Purpose
Cli_FullUpload	Uploads a block from AG with Header and Footer infos.
Cli_Upload	Uploads a block from AG.
Cli_Download	Download a block into AG.
Cli_Delete	Delete a block into AG.
Cli_DBGet	Uploads a DB from AG using DBRead.
Cli_DBFill	Fills a DB in AG with a given byte.

Date/Time functions

These functions allow to read/modify the date and time of a PLC.

Imagine a production line in which each PLC saves the data with date/time field inside, it is very important that the date be up to date.

Both CP X43 and internal PN allow to synchronize date and time but you need an NTP server, and in some cases (old hardware or CP343-1 Lean or old firmware release) this doesn’t work properly.

Snap7 Client, using the same method of S7 Manager, always works.

Function	Purpose
Cli_GetPlcDateTime	Returns the PLC date/time.
Cli_SetPlcDateTime	Sets the PLC date/time with a given value.
Cli_SetPlcSystemDateTime	Sets the PLC date/time with the host (PC) date/time.

System info functions

these functions access to SZL (or SSL - System Status List) to give you all the same information that you can get from S7 Manager.

System Status List

The system status list (SSL) describes the current status of a programmable logic controller.

The contents of the SSL can only be read using information functions but cannot be modified. The partial lists are virtual lists, in other words, they are only created by the operating system of the CPUs when specifically requested.

You can access to system status list using SFC 51 too "RDSYSST."

To read a partial list you must specify its ID and Index.

For a detailed description of SZL see:

§33 of  "System Software for S7-300/400 System and Standard Functions".

Function	Purpose
Cli_ReadSZL	Reads a partial list of given ID and Index.
Cli_ReadSZLList	Reads the list of partial lists available in the CPU.
Cli_GetOrderCode	Returns the CPU order code.
Cli_GetCpuInfo	Returns some information about the AG.
Cli_GetCpInfo	Returns some information about the CP (communication processor).

PLC control functions

With these control function it’s possible to Start/Stop a CPU and perform some other maintenance tasks.

Function	Purpose
Cli_PlcHotStart	Puts the CPU in RUN mode performing an HOT START.
Cli_PlcColdStart	Puts the CPU in RUN mode performing a COLD START.
Cli_PlcStop	Puts the CPU in STOP mode.
Cli_CopyRamToRom	Performs the Copy Ram to Rom action.
Cli_Compress	Performs the Compress action.
Cli_GetPlcStatus	Returns the CPU status (running/stopped).

Security functions

With these functions is possible to know the current protection level, and to set/clear the current session password.

The correct name of the below functions Cli_SetSessionPassword and Cli_ClearSessionPassword, would have to be Cli_Login and Cli_Logout to avoid misunderstandings about their scope.

Especially because, if you look at the source code, there is an encoding function that translates the plain password before send it to the PLC.

PASSWORD HACKING IS VERY FAR FROM THE AIM OF THIS PROJECT, MOREOVER YOU NEED TO KNOW THE CORRECT PASSWORD TO MEET THE CPU SECURITY LEVEL.

Detailed information about the protection level can be found in §33.19 of  "System Software for S7-300/400 System and Standard Functions".

Function	Purpose
Cli_SetSessionPassword	Send the password to the PLC to meet its security level.
Cli_ClearSessionPassword	Clears the password set for the current session (logout).
Cli_GetProtection	Gets the CPU protection level info.

Low level functions

Snap7 hides the IsoTCP underlying layer. With this function however, it’s possible to exchange an IsoTCP telegram with a PLC.

Function	Purpose
Cli_IsoExchangeBuffer	Exchanges a given S7 PDU (protocol data unit) with the CPU.

Miscellaneous functions

These are utility functions.

Function	Purpose
Cli_GetExecTime	Returns the last job execution time in milliseconds.
Cli_GetLastError	Returns the last job result.
Cli_GetPduLength	Returns info about the PDU length (requested and negotiated).
Cli_ErrorText	Returns a textual explanation of a given error number.

Cli_GetConnected

Returns the connection state.

Asynchronous functions

These functions are executed in a separate thread simultaneously to the execution of the caller program.

Function	Purpose
Cli_AsReadArea	Reads a data area from a PLC.
Cli_AsWriteArea	Writes a data area into a PLC.
Cli_AsDBRead	Reads a part of a DB from a PLC.
Cli_AsDBWrite	Writes a part of a DB into a PLC.
Cli_AsABRead	Reads a part of IPU area from a PLC.
Cli_AsABWrite	Writes a part of IPU area into a PLC.
Cli_AsEBRead	Reads a part of IPI area from a PLC.
Cli_AsEBWrite	Writes a part of IPI area into a PLC.
Cli_AsMBRead	Reads a part of Merkers area from a PLC.
Cli_AsMBWrite	Writes a part of Merkers area into a PLC.
Cli_AsTMRead	Reads timers from a PLC.
Cli_AsTMWrite	Write timers into a PLC.
Cli_AsCTRead	Reads counters from a PLC.
Cli_AsCTWrite	Write counters into a PLC.
Cli_AsListBlocksOfType	Returns the AG blocks list of a given type.
Cli_AsReadSZL	Reads a partial list of given ID and Index.
Cli_AsReadSZLList	Reads the list of partial lists available in the CPU.
Cli_AsFullUpload	Uploads a block from AG with Header and Footer infos.
Cli_AsUpload	Uploads a block from AG.
Cli_AsDownload	Download a block into AG.
Cli_AsDBGet	Uploads a DB from AG using DBRead.
Cli_AsDBFill	Fills a DB in AG with a given byte.
Cli_AsCopyRamToRom	Performs the Copy Ram to Rom action.
Cli_AsCompress	Performs the Compress action.

Server API

In the manual you will find detailed information about syntax, parameters and examples, please refer to it.

Administrative functions

These functions allow controlling the behavior a Server Object.

Function	Purpose
Srv_Create	Creates a Server Object.
Srv_Destroy	Destroys a Server Object.
Srv_StartTo	Starts a Server Object onto a given IP Address.
Srv_Start	Starts a Server Object onto the default adapter.
Srv_Stop	Stops the Server.
Srv_GetParam	Reads an internal Server parameter.
Srv_SetParam	Writes an internal Server Parameter.

Shared memory functions

These functions allow to share data between the user application and the server.

Function	Purpose
Srv_RegisterArea	Shares a given memory area with the server.
Srv_UnRegisterArea	“Unshares” a memory area previously shared.
Srv_LockArea	Locks a shared memory area.
Srv_UnlockArea	Unlocks a previously locked shared memory area.

Control flow functions

These functions allow to setup/handle the events generated by a server.

Function	Purpose
Srv_SetReadEventsCallback	Sets the user Read event callback.
Srv_SetEventsCallback	Sets the user callback that the Server object has to call when an event is created.
Srv_GetMask	Reads the specified filter mask.
Srv_SetMask	Writes the specified filter mask.
Srv_PickEvent	Extracts an event (if available) from the Events queue.
Srv_ClearEvents	Empties the Event queue.

Miscellaneous functions

These are utility functions.

Function	Purpose
Srv_GetStatus	Returns the last job execution time in milliseconds.
Srv_SetCpuStatus	Returns the last job result.
Srv_EventText	Returns a textual explanation of a given event.
Srv_ErrorText	Returns a textual explanation of a given error number.

Partner API

In the manual you will find detailed information about syntax, parameters and examples, please refer to it.

Administrative functions

These functions allow controlling the behavior a Partner Object.

Function	Purpose
Par_Create	Creates a Partner Object.
Par_Destroy	Destroys a Partner Object.
Par_StartTo	Starts a Partner Object onto a given IP Address.
Par_Start	Starts a Partner Object onto the previous parameters supplied.
Par_Stop	Stops the Partner.
Par_GetParam	Reads an internal Partner parameter.
Par_SetParam	Writes an internal Partner Parameter.
Par_SetSendCallback	Sets the user callback that the Partner object has to call when the asynchronous data sent is complete.
Par_SetRecvCallback	Sets the user callback that the Partner object has to call when a data packet is incoming.

Data Transfer functions

These functions allow the Partner to exchange data with its counterpart into a PLC.

Function	Purpose
Par_BSend	Sends a data packet to the partner.
Par_AsBSend	Sends an asynchronous data packet to the partner.
Par_CheckAsBSendCompletion	Checks if the current asynchronous job was completed.
Par_WaitAsBSendCompletion	Waits until the current asynchronous send job is done.
Par_BRecv	Receives a data packet from the partner.
Par_CheckAsBRecvCompletion	Checks if a packed received was received.

Miscellaneous functions

These are utility functions.

Function	Purpose
Par_GetTimes	Returns the last send and recv jobs execution time in milliseconds.
Par_GetStats	Returns some statistics.
Par_GetLastError	Returns the last job result.
Par_GetStatus	Returns the Partner status.
Par_ErrorText	Returns a textual explanation of a given error number.