libdcmtk2-dev 3.6.0-9 / usr / include / dcmtk / dcmnet / dfindscu.h

/*
 *
 *  Copyright (C) 1994-2010, OFFIS e.V.
 *  All rights reserved.  See COPYRIGHT file for details.
 *
 *  This software and supporting documentation were developed by
 *
 *    OFFIS e.V.
 *    R&D Division Health
 *    Escherweg 2
 *    D-26121 Oldenburg, Germany
 *
 *
 *  Module:  dcmnet
 *
 *  Author:  Marco Eichelberg / Andrew Hewett
 *
 *  Purpose: Classes for Query/Retrieve Service Class User (C-FIND operation)
 *
 *  Last Update:      $Author: joergr $
 *  Update Date:      $Date: 2010-10-14 13:17:22 $
 *  CVS/RCS Revision: $Revision: 1.5 $
 *  Status:           $State: Exp $
 *
 *  CVS/RCS Log at end of file
 *
 */

#ifndef DFINDSCU_H
#define DFINDSCU_H

#include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */
#include "dcmtk/ofstd/ofcond.h"    /* for class OFCondition */
#include "dcmtk/dcmdata/dcxfer.h"  /* for E_TransferSyntax */
#include "dcmtk/dcmnet/dimse.h"    /* for T_DIMSE_BlockingMode */

// forward declarations of classes and structs
class DcmDataset;
class DcmTransportLayer;
class OFConsoleApplication;
struct T_ASC_Association;
struct T_ASC_Parameters;
struct T_DIMSE_C_FindRQ;
struct T_DIMSE_C_FindRSP;

/** Abstract base class for Find SCU callbacks. During a C-FIND operation, the 
 *  callback() method of a callback handler object derived from this class is 
 *  called once for each incoming C-FIND-RSP message. The callback method has 
 *  access to the original C-FIND-RQ message (but not the request dataset), the 
 *  current C-FIND-RSP message including its dataset, the number of the current 
 *  request, the association over which the request is received and the 
 *  presentation context ID. The callback is needed to process the incoming
 *  message (e.g., display on screen, add to some list, store to file). The
 *  callback may also issue a C-FIND-CANCEL message if needed. Implementations
 *  may provide their own callbacks, which must be derived from this base
 *  class.
 */
class DcmFindSCUCallback 
{ 
public: 

  /// default constructor
  DcmFindSCUCallback();
  
  /// destructor
  virtual ~DcmFindSCUCallback() {}

  /** callback method that is called once for each incoming C-FIND-RSP message.
   *  @param request DIMSE command of the original C-FIND request
   *  @param responseCount number of current response
   *  @param rsp DIMSE command of incoming C-FIND response
   *  @param responseIdentifiers dataset of incoming C-FIND response
   */
  virtual void callback(
        T_DIMSE_C_FindRQ *request,
        int responseCount,
        T_DIMSE_C_FindRSP *rsp,
        DcmDataset *responseIdentifiers) = 0;

  /** assigns a value to member variable assoc_. Used by FindSCU code 
   *  (class DcmFindSCU) to store a pointer to the current association
   *  before the callback object is used.
   *  @param assoc pointer to current association
   */
  void setAssociation(T_ASC_Association *assoc);

  /** assigns a value to member variable presId_. Used by FindSCU code 
   *  (class DcmFindSCU) to store the current presentation context ID
   *  before the callback object is used.
   *  @param presId current presentation context ID
   */
  void setPresentationContextID(T_ASC_PresentationContextID presId);

protected: /* the two member variables are protected and can be accessed from derived classes */
	
   /// pointer to current association. Will contain valid value when callback() is called.
   T_ASC_Association *assoc_;

   /// current presentation context ID. Will contain valid value when callback() is called.
   T_ASC_PresentationContextID presId_;
};


/** Default implementation of FindSCU callback class. This implementation is 
 *  used when no explicit callback is passed by the user, e.g. in the findscu tool.
 */
class DcmFindSCUDefaultCallback: public DcmFindSCUCallback
{
public:
  /** constructor
   *  @param extractResponsesToFile if true, C-FIND-RSP datasets will be stored as DICOM files
   *  @param cancelAfterNResponses if non-negative, a C-FIND-CANCEL will be issued after the
   *    given number of incoming C-FIND-RSP messages
   */
  DcmFindSCUDefaultCallback(
    OFBool extractResponsesToFile,
    int cancelAfterNResponses);
  
  /// destructor
  virtual ~DcmFindSCUDefaultCallback() {}

  /** callback method that is called once for each incoming C-FIND-RSP message.
   *  @param request DIMSE command of the original C-FIND request
   *  @param responseCount number of current response
   *  @param rsp DIMSE command of incoming C-FIND response
   *  @param responseIdentifiers dataset of incoming C-FIND response
   */
  virtual void callback(
        T_DIMSE_C_FindRQ *request,
        int responseCount,
        T_DIMSE_C_FindRSP *rsp,
        DcmDataset *responseIdentifiers);

private:

   /// if true, C-FIND-RSP datasets will be stored as DICOM files
   OFBool extractResponsesToFile_;

   /// if non-negative, a C-FIND-CANCEL will be issued after the given number of incoming C-FIND-RSP messages
   int cancelAfterNResponses_;
};


/** This class implements a complete DICOM C-FIND SCU, including association set-up, execution of the
 *  C-FIND transaction including processing of results, and closing of the association. By default,
 *  incoming C-FIND-RSP messages will be displayed on console and, optionally, also stored in files.
 *  By providing a user-defined callback, other types of processing are possible.
 */
class DcmFindSCU
{
public:

  /// constructor, does not execute any network-related code
  DcmFindSCU();

  /// destructor. Destroys network structure if not done already.
  virtual ~DcmFindSCU();

  /** initialize the network structure. This should be done only once.
   *  @param acse_timeout timeout for ACSE operations, in seconds
   *  @return EC_Normal if successful, an error code otherwise
   */
  OFCondition initializeNetwork(int acse_timeout);

  /** enable user-defined transport layer. This method is needed when
   *  the network association should use a non-default transport layer
   *  (e.g. a TLS connection). In this case a fully initialized transport
   *  layer object must be passed with this call after a call to 
   *  initializeNetwork, but prior to any call to performQuery.
   *  The transport layer object will not be deleted by this class and
   *  must remain alive until this object is deleted or a new transport
   *  layer is set.
   *  @param tLayer pointer to transport layer object
   *  @return EC_Normal if successful, an error code otherwise
   */
  OFCondition setTransportLayer(DcmTransportLayer *tLayer);

  /** destroy network struct. This should be done only once.
   *  @return EC_Normal if successful, an error code otherwise
   */
  OFCondition dropNetwork();

  /** main worker method that negotiates an association, executes one or more 
   *  C-FIND-RQ transactions, processes the responses and closes the association 
   *  once everything is finished (or an error has occured).
   *  @param peer hostname or IP address of peer SCP host
   *  @param port TCP port number of peer SCP host
   *  @param ourTitle calling AE title
   *  @param peerTitle called AE title
   *  @param abstractSyntax SOP Class UID or Meta SOP Class UID of service
   *  @param preferredTransferSyntax. May be Unknown, Implicit Little Endian, or any of the
   *    two uncompressed explicit VR transfer syntaxes. By default (unknown), local endian
   *    explicit VR is proposed first, followed by opposite endian explicit VR, followed by
   *    implicit VR. This behaviour can be modified by explicitly specifying the preferred
   *    explicit VR transfer syntax. With Little Endian Implicit, only Implicit VR is proposed.
   *  @param blockMode DIMSE blocking mode
   *  @param dimse_timeout timeout for DIMSE operations (in seconds)
   *  @param maxReceivePDULength limit the maximum PDU size for incoming PDUs to the given value.
   *    This value should be less than or equal to ASC_DEFAULTMAXPDU, and is usually identical
   *    to ASC_DEFAULTMAXPDU (other values are only useful for debugging purposes).
   *  @param secureConnection this flag, if true, requests a secure TLS connection to be used
   *    instead of a normal connection. This will only work if DCMTK has been compiled with
   *    OpenSSL support (WITH_OPENSSL) and if a transport layer object supporting secure
   *    connections has been set with setTransportLayer() prior to this call.
   *  @param abortAssociation abort association instead of releasing it (for debugging purposes)
   *  @param repeatCount number of times this query should be repeated
   *    (for debugging purposes, works only with default callback)
   *  @param extractResponsesToFile if true, extract incoming response messages to file
   *    (works only with default callback)
   *  @param cancelAfterNResponses issue C-FIND-CANCEL after given number of responses
   *    (works only with default callback)
   *  @param overrideKeys list of keys/paths that override those in the query files, if any.
   *    Either the list of query files or override keys or both should be non-empty, because the query
   *    dataset will be empty otherwise. For path syntax see DcmPath.
   *  @param callback user-provided non-default callback handler object. 
   *    For default callback, pass NULL.
   *  @param fileNameList list of query files. Each file is expected to be a DICOM file
   *    containing a dataset that is used as a query, possibly modified by override keys, if any.
   *    This parameter, if non-NULL, points to a list of filenames (paths).
   *  @return EC_Normal if successful, an error code otherwise
   */  
  OFCondition performQuery(
    const char *peer,
    unsigned int port,
    const char *ourTitle,
    const char *peerTitle,
    const char *abstractSyntax,
    E_TransferSyntax preferredTransferSyntax,
    T_DIMSE_BlockingMode blockMode,
    int dimse_timeout,
    Uint32 maxReceivePDULength,
    OFBool secureConnection,
    OFBool abortAssociation,
    unsigned int repeatCount,
    OFBool extractResponsesToFile,
    int cancelAfterNResponses,
    OFList<OFString> *overrideKeys,
    DcmFindSCUCallback *callback = NULL,
    OFList<OFString> *fileNameList = NULL);    

  /** static helper function that writes the content of the given dataset
   *  into a DICOM file (using the DICOM file format with metaheader).
   *  This method produces a temporary copy of the dataset and should, therefore,
   *  not be used with very large datasets.
   *  @param ofname filename to write
   *  @param dataset dataset to store in file
   *  @return EC_Normal if successful, an error code otherwise
   */   
  static OFBool writeToFile(const char* ofname, DcmDataset *dataset);

private:

  /** add presentation context for given abstract syntax and given preferred transfer syntax
   *  to the ACSE parameter struct. 
   *  @param params ACSE parameter struct to be modified
   *  @param abstractSyntax SOP Class UID or Meta SOP Class UID of service
   *  @param preferredTransferSyntax. May be Unknown, Implicit Little Endian, or any of the
   *    two uncompressed explicit VR transfer syntaxes. By default (unknown), local endian
   *    explicit VR is proposed first, followed by opposite endian explicit VR, followed by
   *    implicit VR. This behaviour can be modified by explicitly specifying the preferred
   *    explicit VR transfer syntax. With Little Endian Implicit, only Implicit VR is proposed.
   *  @return EC_Normal if successful, an error code otherwise
   */   
  OFCondition addPresentationContext(
    T_ASC_Parameters *params, 
    const char *abstractSyntax,
    E_TransferSyntax preferredTransferSyntax);

  /** perform a single C-FIND transaction on association that is already open.
   *  @param assoc DIMSE association
   *  @param fname file name for the query file to be used with this query. May be NULL.
   *  @param repeatCount number of times this query should be repeated
   *    (for debugging purposes, works only with default callback)
   *  @param abstractSyntax SOP Class UID or Meta SOP Class UID of service
   *  @param blockMode DIMSE blocking mode
   *  @param dimse_timeout timeout for DIMSE operations (in seconds)
   *  @param extractResponsesToFile if true, extract incoming response messages to file
   *    (works only with default callback)
   *  @param cancelAfterNResponses issue C-FIND-CANCEL after given number of responses
   *    (works only with default callback)
   *  @param overrideKeys dataset with keys that override those in the query file, if any.
   *    Either query file or override keys or both should be non-empty, because the query
   *    dataset will be empty otherwise.
   *  @param callback user-provided non-default callback handler object. 
   *    For default callback, pass NULL.
   *  @return EC_Normal if successful, an error code otherwise
   */   
  OFCondition findSCU(
    T_ASC_Association * assoc, 
    const char *fname, 
    int repeatCount,  
    const char *abstractSyntax,
    T_DIMSE_BlockingMode blockMode, 
    int dimse_timeout, 
    OFBool extractResponsesToFile,
    int cancelAfterNResponses,
    OFList<OFString> *overrideKeys,
    DcmFindSCUCallback *callback = NULL) const;

private:
	
  /// pointer to network structure
  T_ASC_Network *net_;

};

#endif

/*
 * CVS Log
 * $Log: dfindscu.h,v $
 * Revision 1.5  2010-10-14 13:17:22  joergr
 * Updated copyright header. Added reference to COPYRIGHT file.
 *
 * Revision 1.4  2009-11-18 11:53:58  uli
 * Switched to logging mechanism provided by the "new" oflog module.
 *
 * Revision 1.3  2009-07-10 13:21:04  onken
 * Moved override key functionality to DcmPathProcessor.
 *
 * Revision 1.2  2009-07-08 16:14:25  onken
 * Added support for specifying tag paths as override keys.
 *
 * Revision 1.1  2007-02-19 13:13:28  meichel
 * Refactored findscu code into class DcmFindSCU, which is now part of the dcmnet
 *   library, and a short command line tool that only evaluates command line
 *   parameters and then makes use of this class. This facilitates re-use of the
 *   findscu code in other applications.
 *
 *
 */