SalDDE
Namespace: PPJ.Runtime.DDE
Assembly: PPJ.Runtime.DDE.50 (5.0.0.0)
Provides SAL-compatible DDE conversations, server notifications, global atoms, and Windows DDE message helpers.
- C#
- VB.NET
public class SalDDE
Public Class SalDDE
The control-based methods translate the target control and report native DDE failures as false. Low-level methods expose native handles; the application must follow the ownership rules of the corresponding Windows DDE message.
Example:
using PPJ.Runtime.DDE;
using PPJ.Runtime;
SalNumber atom = SalDDE.AddAtom("MyTopic");
if (atom != 0)
{
SalString name = SalString.Null;
SalDDE.GetAtomName(atom, ref name, 256);
SalDDE.DeleteAtom(atom);
}
Methods
AddAtom(stringToAdd)
Adds a string to the Windows global atom table, incrementing its reference count if it already exists.
| Parameter | Type | Description |
|---|---|---|
| stringToAdd | SalString | The string to register in the global atom table. |
Returns: SalNumber. The atom identifier returned by Windows, or zero on failure.
Alloc()
Allocates an initially empty, movable global memory object for a DDE payload.
Returns: SalNumber. The native memory handle, or zero if allocation fails.
Populate the handle with a payload-writing helper before sending it.
DeleteAtom(atomToDelete)
Decrements the reference count of a global atom and removes it when the count reaches zero.
| Parameter | Type | Description |
|---|---|---|
| atomToDelete | SalNumber | The atom identifier whose reference is released. |
Returns: SalNumber. The result returned by Windows; zero indicates success.
Extract(msg, wParam, lParam, sender, lowlParam, highlParam)
Unpacks a Windows DDE message into its sender and message-specific low and high values.
| Parameter | Type | Description |
|---|---|---|
| msg | SalNumber | The Windows DDE message identifier. |
| wParam | SalNumber | The message wParam containing the sender window handle. |
| lParam | SalNumber | The packed or message-specific lParam. |
sender  | SalWindowHandle | The sender window handle; for extraction, receives the handle on success. |
| lowlParam | SalNumber | The low value associated with the DDE message; receives the unpacked value during extraction. |
| highlParam | SalNumber | The high value associated with the DDE message; receives the unpacked value during extraction. |
Returns: SalBoolean. True for a supported message that was unpacked successfully; otherwise false.
For packed messages, this method frees the packed lParam after unpacking. Output parameters are assigned only on success.
ExtractCmd(handle, command, commandSize)
Reads command text from a global memory handle carried by a WM_DDE_Execute message.
| Parameter | Type | Description |
|---|---|---|
| handle | SalNumber | The global memory handle containing the payload. |
| command | SalString | The command text; for extraction, receives the text on success. |
| commandSize | SalNumber | Reserved for compatibility; ignored. |
Returns: SalBoolean. True if the memory handle could be locked and read; otherwise false.
The compatibility size argument is ignored; the text is read to its native terminator.
ExtractDataText(handle, status, data, dataSize)
Reads the status word and text buffer from a DDE data or poke memory block.
| Parameter | Type | Description |
|---|---|---|
| handle | SalNumber | The global memory handle containing the payload. |
| status | SalNumber | The DDE status word; receives the extracted status when reading. |
| data | SalString | The payload; receives the response when reading. |
| dataSize | SalNumber | The maximum number of bytes copied into the decoding buffer. |
Returns: SalBoolean. True if the block can be locked and its format is supported; otherwise false.
Only CF_TEXT and CF_UNICODETEXT are accepted. Bytes are copied until the first zero byte or the requested buffer size; the entire allocated buffer is decoded.
ExtractOptions(options, flags, format)
Reads the status and clipboard-format words from a DDE advice-options memory block.
| Parameter | Type | Description |
|---|---|---|
| options | SalNumber | The global memory handle for the advice-options block. |
| flags | SalNumber | The DDE advice flags; receives the flags when reading. |
| format | SalNumber | The numeric Windows clipboard format. |
Returns: SalBoolean. True if the memory could be locked and read; otherwise false.
FindAtom(topicString)
Looks up a string in the Windows global atom table without adding a reference.
| Parameter | Type | Description |
|---|---|---|
| topicString | SalString | The string to find in the global atom table. |
Returns: SalNumber. The existing atom identifier, or zero when it is not found.
Free(memory)
Releases a global memory object allocated for a DDE payload.
| Parameter | Type | Description |
|---|---|---|
| memory | SalNumber | The global memory handle to release. |
Returns: SalNumber. Zero on success, or the memory handle if Windows could not free it.
GetAtomName(atom, atomName, stringLength)
Copies the string associated with a global atom into a SAL string.
| Parameter | Type | Description |
|---|---|---|
| atom | SalNumber | The atom identifier to query. |
| atomName | SalString | Receives the atom text. |
| stringLength | SalNumber | The native text buffer capacity, including room for the terminating null. |
Returns: SalNumber. The number of characters copied, excluding the terminating null, or zero on failure.
GetExecuteString(msglParam)
Retrieves command text from the managed handle carried by SAM_DDE_ClientExecute.
| Parameter | Type | Description |
|---|---|---|
| msglParam | SalNumber | The managed command handle supplied with SAM_DDE_ClientExecute. |
Returns: SalString. The command text, or Null when the input is zero or the handle is unallocated.
Use this only with the handle supplied during that SAL event; it is not a native WM_DDE_Execute memory handle.
Post(wndReceiver, message, wndSender, lowlParam, hnighlParam)
Packs and posts an asynchronous Windows DDE message.
| Parameter | Type | Description |
|---|---|---|
| wndReceiver | SalWindowHandle | The destination window handle. |
| message | SalNumber | The Windows DDE message identifier. |
| wndSender | SalWindowHandle | The sending window handle. |
| lowlParam | SalNumber | The low value associated with the DDE message; receives the unpacked value during extraction. |
| hnighlParam | SalNumber | The high value to pack into the message. |
Returns: SalNumber. The native PostMessage result; zero indicates failure or a rejected initiation message.
WM_DDE_Initiate is rejected. If posting fails, any packed lParam allocated by this method is freed.
Request(ctrl, service, serverTopic, serverItem, timeout, data)
Opens a temporary conversation, requests an item, and raises SAM_DDE_DataChange on the target control.
| Parameter | Type | Description |
|---|---|---|
| ctrl | Control | The control associated with the SAL DDE operation. |
| service | SalString | The DDE service name. |
| serverTopic | SalString | The server topic. |
| serverItem | SalString | The item to request; converted to uppercase before the request. |
| timeout | SalNumber | The transaction timeout, in milliseconds. |
| data | SalString | The payload; receives the response when reading. |
Returns: SalBoolean. True on success; false if the control is unavailable or a DDE operation fails.
The item name is converted to uppercase. The connection is disposed after the request, and the output is assigned only after the notification has been raised.
Send(receiver, message, sender, lowlParam, highlParam)
Packs and synchronously sends a Windows DDE message.
| Parameter | Type | Description |
|---|---|---|
| receiver | SalWindowHandle | The destination window handle. |
| message | SalNumber | The Windows DDE message identifier. |
| sender | SalWindowHandle | The sender window handle; for extraction, receives the handle on success. |
| lowlParam | SalNumber | The low value associated with the DDE message; receives the unpacked value during extraction. |
| highlParam | SalNumber | The high value associated with the DDE message; receives the unpacked value during extraction. |
Returns: SalNumber. The native result returned by the receiving window.
WM_DDE_Ack is packed as a response to WM_DDE_Initiate.
SendAll(message, sender, lowlParam, highlParam)
Packs and broadcasts a Windows DDE message to top-level windows.
| Parameter | Type | Description |
|---|---|---|
| message | SalNumber | The Windows DDE message identifier. |
| sender | SalWindowHandle | The sender window handle; for extraction, receives the handle on success. |
| lowlParam | SalNumber | The low value associated with the DDE message; receives the unpacked value during extraction. |
| highlParam | SalNumber | The high value associated with the DDE message; receives the unpacked value during extraction. |
Returns: SalNumber. The result returned by the native broadcast operation.
The overload with a timeout uses the native timed send operation.
SendAll(message, sender, lowlParam, highlParam, timeout)
Packs and broadcasts a Windows DDE message to top-level windows.
| Parameter | Type | Description |
|---|---|---|
| message | SalNumber | The Windows DDE message identifier. |
| sender | SalWindowHandle | The sender window handle; for extraction, receives the handle on success. |
| lowlParam | SalNumber | The low value associated with the DDE message; receives the unpacked value during extraction. |
| highlParam | SalNumber | The high value associated with the DDE message; receives the unpacked value during extraction. |
| timeout | SalNumber | The transaction timeout, in milliseconds. |
Returns: SalNumber. The result returned by the native broadcast operation.
The overload with a timeout uses the native timed send operation.
SendExecute(ctrl, service, topic, item, timeout, command)
Opens a temporary conversation and asks the server to execute a command.
| Parameter | Type | Description |
|---|---|---|
| ctrl | Control | The control associated with the SAL DDE operation. |
| service | SalString | The DDE service name. |
| topic | SalString | The conversation topic. |
| item | SalString | Reserved for compatibility; ignored. |
| timeout | SalNumber | The transaction timeout, in milliseconds. |
| command | SalString | The command text; for extraction, receives the text on success. |
Returns: SalBoolean. True on success; false if the control is unavailable or a DDE operation fails.
The item parameter is retained for compatibility and is not used. The temporary conversation is always disposed.
SendToClient(ctrl, data, clientID, timeout)
Supplies a requested response or updates subscribed clients for the control's server.
| Parameter | Type | Description |
|---|---|---|
| ctrl | Control | The control associated with the SAL DDE operation. |
| data | SalString | The payload; receives the response when reading. |
| clientID | SalNumber | The pending request identifier, or zero to update subscribed clients. |
| timeout | SalNumber | Reserved for compatibility; ignored. |
Returns: SalBoolean. True when the response is assigned or the item update succeeds; otherwise false.
A nonzero client ID identifies the event arguments for a pending SAM_DDE_ClientRequest. A zero ID updates the server's current item and posts change notifications.
SetCmd(highlParam, command)
Resizes a global memory block and writes command text using the default encoding.
| Parameter | Type | Description |
|---|---|---|
| highlParam | SalNumber | The global memory handle for the command block. |
| command | SalString | The command text; for extraction, receives the text on success. |
Returns: SalBoolean. True if the block was resized, locked, and written; otherwise false.
SetData(handle, status, data, format)
Resizes a DDE data block and writes status, clipboard format, and the supplied bytes.
| Parameter | Type | Description |
|---|---|---|
| handle | SalNumber | The global memory handle containing the payload. |
| status | SalNumber | The DDE status word; receives the extracted status when reading. |
| data | Byte[] | The payload; receives the response when reading. |
| format | Int32 | The numeric Windows clipboard format. |
Returns: SalBoolean. True if the block was resized, locked, and written; otherwise false.
SetDataText(numData, status, strData)
Resizes a DDE data block and writes its status word, CF_UNICODETEXT format, and Unicode payload.
| Parameter | Type | Description |
|---|---|---|
| numData | SalNumber | The global memory handle for the data block. |
| status | SalNumber | The DDE status word; receives the extracted status when reading. |
| strData | SalString | The Unicode text to place in the data block. |
Returns: SalBoolean. True if the block was resized, locked, and written; otherwise false.
SetOptions(options, flags, format)
Resizes an advice-options block and writes its two words.
| Parameter | Type | Description |
|---|---|---|
| options | SalNumber | The global memory handle for the advice-options block. |
| flags | SalNumber | The DDE advice flags; receives the flags when reading. |
| format | SalNumber | The numeric Windows clipboard format. |
Returns: SalBoolean. True if the block was resized, locked, and written; otherwise false.
The current implementation writes the flags value to both words; the format argument is not used.
StartServer(ctrl, service, topic, item)
Associates a DDE server for a service, topic, and item with a control.
| Parameter | Type | Description |
|---|---|---|
| ctrl | Control | The control associated with the SAL DDE operation. |
| service | SalString | The DDE service name. |
| topic | SalString | The conversation topic. |
| item | SalString | The item associated with the conversation. |
Returns: SalBoolean. True on success; false if the control is unavailable or DDE registration fails.
StartSession(ctrl, service, topic, item, timeout)
Associates an item-change subscription with a control.
| Parameter | Type | Description |
|---|---|---|
| ctrl | Control | The control associated with the SAL DDE operation. |
| service | SalString | The DDE service name. |
| topic | SalString | The conversation topic. |
| item | SalString | The item associated with the conversation. |
| timeout | SalNumber | The transaction timeout, in milliseconds. |
Returns: SalBoolean. True on success; false if the control is unavailable or a DDE operation fails.
Incoming changes are routed through the SAL DDE window-action messages.
StopServer(ctrl)
Disconnects the DDE server associated with a control.
| Parameter | Type | Description |
|---|---|---|
| ctrl | Control | The control associated with the SAL DDE operation. |
Returns: SalBoolean. True when a server association is stopped; otherwise false.
StopSession(ctrl)
Disconnects the DDE subscription associated with a control.
| Parameter | Type | Description |
|---|---|---|
| ctrl | Control | The control associated with the SAL DDE operation. |
Returns: SalBoolean. True when a client association is stopped; otherwise false.