L_DicomListenExt

Show in webframe

#include "ltdic.h"

L_LTDIC_API L_INT L_DicomListenExt(hNet, pszHostAddress, nHostPort, nNbPeers, nIpType)

HDICOMNET hNet;	/* a DICOM Network handle */
L_TCHAR * pszHostAddress;	/* host IP address */
L_UINT nHostPort;	/* host port number */
L_INT nNbPeers;	/* backlog parameter */
L_INT nIpType;	/* type of IP address */

Establishes a connection to listen to for incoming connection requests.

Parameter

Description

hNet

A DICOM Network handle. This is the handle returned from the L_DicomCreateNet function.

pszHostAddress

Character string that contains the IP address of the host computer (the server's address).

nHostPort

Port number of the host (the server's port).

nNbPeers

Value passed to the WinSock listen() function for the backlog parameter that limits the size of the queue for waiting connections.

nIpType

The type of IP address. Possible values are:

Value	Meaning
DICOM_IPTYPE_NONE	[0x000] Provided for initialization.
DICOM_IPTYPE_IPV4	[0x001] Only use IPv4 addresses.
DICOM_IPTYPE_IPV6	[0x002] Only use IPv6 addresses.
DICOM_IPTYPE_IPV4_OR_IPV6	[0x003] Use both IPv4 and IPv6 addresses.

Returns

DICOM_SUCCESS	The function was successful.
>0	An error occurred. Refer to Return Codes.

Comments

L_DicomListenExt() is an extension of L_DicomListen() that allows you to specify which type of Internet Protocol Version to use.

If pszHostAddress is "" or NULL, the IP address will be the local computer's address.

If pszHostAddress is "*", the IP address will be all of the local computer's addresses. This is useful if the local computer has more than one network interface and address.

If nHostPort is 0, the port number will be the number of the first available port.

To connect to a server as a client, you must first create and initialize a handle to the DICOM Network using L_DicomCreateNet. Next, set the callback functions you will use by calling L_DicomSetCallback. Then call L_DicomConnect or L_DicomConnectExt (if IPv6 support is needed) to establish the connection.

To use your computer as a server, you must first create and initialize a handle to the DICOM Network using L_DicomCreateNet. Next, set the callback functions you will use by calling L_DicomSetCallback. Then call L_DicomListen or L_DicomListenExt to listen for incoming connection requests.

L_DicomListenExt() is an extension of L_DicomListen() that allows you to specify the type of Internet Protocol Version to use. Pass DICOM_IPTYPE_IPV4 for nIpType to support the Internet Protocol version 4 (IPv4), which is the standard "dotted quad" 32-bit address format that has been in use since 1981. An example of an IPv4 address is 192.168.0.195

Pass DICOM_IPTYPE_IPV6 for nIpType to support Internet Protocol Version Version 6 (IPv6). IPv6 uses a 128-bit address format. An example of an IPv6 address is fe80::18bd:81f:6b02:759f

To support both IPv4 and Ipv6 addresses, pass DICOM_IPTYPE_IPV6 for nIpType.

If the call to L_DicomListenExt fails, make sure that the IP address that you passed for pszHostAddress is a valid address that is accessible within your network. You can verify the accessibility of both IPv4 and IPv6 addresses using the windows ping command. For example, to verify that 192.168.0.195 is accessible within your network, do the following

Start command prompt, and type the following command
ping 192.168.0.195

Note that the following are equivalent:

L_DicomListen(pszHostAddr4ess, nHostPort, nNbPeers);
L_DicomListenExt(pszHostAddr4ess, nHostPort, nNbPeers, DICOM_IPTYPE_IPV4);

The nNbPeers parameter designates the size of the backlog parameter used by the WinSock listen() function. As an example, suppose that the value is set to 3 and that 4 people try to connect at exactly the same time. In such a case, all 4 will be rejected because the connection backlog queue is full. But if one of the connections has been accepted by the time the 4th is made, then all will work.

To determine the number of connected clients and impose a maximum number of connections, perform the following steps:

Use the L_GetClientCount function in the "OnReceiveAssociateRequest" handler.
Compare that value with the maximum number of connections allowed.
If the number of connected clients is greater than the maximum number of connections allowed, send a "SendAssociateReject" command to the client trying to connect.

Required DLLs and Libraries

LTDIC

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

Platforms

Win32, x64, Linux.

See Also

Functions:	L_DicomCreateNet, L_DicomStartUp, L_DicomListen
Topics:	Working with DICOM Network Connections

Example

This sample implements a very basic server that is listening on all local IPv4 and IPv6 addresses. Run this sample first, and then run the sample for L_DicomConnectExt, which is a very basic client that will connect to this server.

// Forward declaration
L_VOID EXT_CALLBACK OnAcceptCB(HDICOMNET hNet, L_INT nError, L_VOID* pUserData);
L_INT DicomListenExtExample(L_VOID)
{
   L_INT nRet = L_DicomStartUp();
   if (nRet != DICOM_SUCCESS)
      return nRet;
   HDICOMNET hServer = L_DicomCreateNet(NULL, DICOM_SECURE_NONE);
   /* set the callbacks */
   DICOMNETCALLBACK cb = {0};
   cb.pfnAccept = (ACCEPTCALLBACK)OnAcceptCB;
   cb.pUserData = NULL;
   L_DicomSetCallback(hServer, &cb);
   // create a server to accept up to 25 clients
   // Listen on all local IP addresses (IPv4 and IPv6)
   nRet = L_DicomListenExt(hServer, TEXT("*"), 104, 25, DICOM_IPTYPE_IPV4_OR_IPV6);
   return nRet;
}
L_VOID EXT_CALLBACK OnAcceptCB(HDICOMNET hNet, L_INT nError, L_VOID* pUserData)
{
   L_TCHAR szMsg[800] = {0};
   L_TCHAR szTemp[800] = {0};
   HDICOMNET hClient = 0;
   L_INT32 lClients = 0;
   L_TCHAR szPeerAddress[200] = {0};
   L_TCHAR szHostAddress[200] = {0};
   L_UINT uPort = 0;
   L_INT nRet = DICOM_SUCCESS;
   L_TCHAR *pszMessageBoxTitle = TEXT("Accept");
   UNREFERENCED_PARAMETER(pUserData);
   wsprintf(szMsg, TEXT("***NetAccept Event ***\n nStatus[%d]\n"), nError);
   if (nError != DICOM_SUCCESS)
   {
      MessageBox(NULL, szMsg, pszMessageBoxTitle, MB_OK);
      return;
   }
   // accept the connection attempt 
   hClient = L_DicomCreateNet(NULL, DICOM_SECURE_NONE);
   L_DicomAccept(hNet, hClient);
   // Here we would normally set the callbacks
   // For this example, we do not set any callbacks
   // For a full example on how to set the callbacks, see the sample for L_DicomListen
   lstrcat(szMsg, TEXT("Accepted\n"));
   // display some information about the connection 
   nRet = L_DicomGetHostInfo(hNet, szHostAddress, 200, &uPort);
   if (nRet != DICOM_SUCCESS)
   {
      MessageBox(NULL, TEXT("Error in OnAcceptCB"), pszMessageBoxTitle, MB_OK);
      return;
   }
   wsprintf(szTemp, TEXT("HostAddress[%s]\nHostPort[%d]\n"), szHostAddress, uPort);
   lstrcat(szMsg, szTemp);
   // Display the client information
   lClients = L_DicomGetClientCount(hNet);
   hClient  = L_DicomGetClient(hNet, lClients - 1);
   wsprintf(szTemp, TEXT("ClientCount[%d]\n"), lClients);
   lstrcat(szMsg, szTemp);
   nRet = L_DicomGetPeerInfo(hClient, szPeerAddress, 200, &uPort);
   if (nRet != DICOM_SUCCESS)
   {
      MessageBox(NULL, TEXT("Error in OnAcceptCB"), pszMessageBoxTitle, MB_OK);
      return;
   }
   wsprintf(szTemp, TEXT("PeerAddress[%s]\nPeerPort[%d]\n"), szPeerAddress, uPort);
   lstrcat(szMsg, szTemp);
   MessageBox(NULL, szMsg, pszMessageBoxTitle, MB_OK);
}