| #include <ddeml.h> |
| HDDEDATA DdeNameService(idInst, hsz1, hszRes, afCmd) | |||||
| DWORD idInst; | /* instance identifier, */ | ||||
| HSZ hsz1; | /* handle of service-name string | */ | |||
| HSZ hszRes; | /* reserved | */ | |||
| UINT afCmd; | /* service-name flags, */ | ||||
The DdeNameService function registers or unregisters the service names that a dynamic data exchange (DDE) server supports. This function causes the system to send XTYP_REGISTER or XTYP_UNREGISTER transactions to other running DDE Management Library (DDEML) client applications.
A server application should call this function to register each service name that it supports and to unregister names that it previously registered but no longer supports. A server should also call this function to unregister its service names just before terminating.
idInst
Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.
hsz1
Identifies the string that specifies the service name that the server is registering or unregistering. An application that is unregistering all of its service names should set this parameter to NULL.
hszRes
Reserved; should be set to NULL.
afCmd
Specifies the service-name flags. This parameter can be one of the following values:
| Value | Meaning |
| DNS_REGISTER | Registers the given service name. |
| DNS_UNREGISTER | Unregisters the given service name. If the hsz1 parameter is NULL, all service names registered by the server will be unregistered. |
| DNS_FILTERON | Turns on service-name initiation filtering. This filter prevents a server from receiving XTYP_CONNECT transactions for service names that it has not registered. This is the default setting for this filter. |
| If a server application does not register any service names, the application cannot receive XTYP_WILDCONNECT transactions. | |
| DNS_FILTEROFF | Turns off service-name initiation filtering. If this flag is set, the server will receive an XTYP_CONNECT transaction whenever another DDE application calls the DdeConnect function, regardless of the service name. |
The return value is nonzero if the function is successful. Otherwise, it is zero.
Use the DdeGetLastError function to retrieve the error value, which may be one of the following:
DMLERR_DLL_NOT_INITIALIZED
DMLERR_DLL_USAGE
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR
The service name identified by the hsz1 parameter should be a base name (that is, the name should contain no instance-specific information). The system generates an instance-specific name and sends it along with the base name during the XTYP_REGISTER and XTYP_UNREGISTER transactions. The receiving applications can then connect to the specific application instance.
The following example initializes an application with the DDEML, creates frequently used string handles, and registers the application's service name:
HSZ hszClock;
HSZ hszTime;
HSZ hszNow;
HINSTANCE hinst;
DWORD idInst = 0L;
FARPROC lpDdeProc;
/* Initialize the application for the DDEML. */
lpDdeProc = MakeProcInstance((FARPROC) DdeCallback, hinst);
if (!DdeInitialize((LPDWORD) &idInst, (PFNCALLBACK) lpDdeProc,
APPCMD_FILTERINITS | CBF_FAIL_EXECUTES, 0L)) {
/* Create frequently used string handles. */
hszTime = DdeCreateStringHandle(idInst, "Time", CP_WINANSI);
hszNow = DdeCreateStringHandle(idInst, "Now", CP_WINANSI);
hszClock = DdeCreateStringHandle(idInst, "Clock", CP_WINANSI);
/* Register the service name. */
DdeNameService(idInst, hszClock, (HSZ) NULL, DNS_REGISTER);
}