readme.txt

Windows CE .Net 下面 VOIP编程的经典实例。对于初学Windows 平台下VOIP编程技术的程序员颇具借鉴意义！

//-----------------------------------------------------------------------------
// Copyright (c) 1998-2002 Microsoft Corporation. All rights reserved.
//-----------------------------------------------------------------------------

Purpose of Program
===================

    VoIPDemo is intended as a sample to show how to use the RTC API for Windows CE, but also
    as a working application for demonstration and use (taking note of the limitations described
    below). 

Limitiations
=============

    Currently supports 1 IM and/or 1 voice call at a time.  
        1 Voice call limitation due to RTC spec.
        1 IM call simplifies event handling + need for multiple session windows

    Simultaneous voice and IM calls are only allowed from one source, currently identified by SIP URI.  
    Callback functionality is currently not implemented.

Component Requirements
======================
SYSGEN_VOIP will bring in all the components required by VoIPDemo. The target device needs to have audio
capture and play capabilities and a network interface.

Overview of program flow and source
====================================
    
    VoIPDemo is separated into three main functional parts: User Interface, use of the RTC API (including
    RTC event handling), and the code to interface between RTC and the UI.  The intent of this quasi-
    layering approach is to limit the direct hooks from the RTC backend to the UI and make it easier to
    re-use the RTC code in a different UI.

    The program goes through the following phases:
    
        Window Initialization
        RTC Initialization
        Main Message Loop
        RTC Termination
        Window Termination


    The main message loop manages all main window UI related messages and events. This includes contact 
    list changes by the user, UI for call placement, etc. When the main window finishes its setup of an
    outgoing call, it calls the SessionWindow Callback to actually initiate the call.

    The SessionWindow is where all voice and IM session UI takes place.  It is called directly by our RTC
    event handler to display call/IM status information, notify the user of incoming calls/messages, 
    parse user input for outgoing messages, and calls the interface code to initiate outgoing sessions.

    Our event handler for RTC interfaces call into the main application window through use of callbacks to the 
    session window and signals presence change notifications directly to the listview objects (through the listview
    functions).  


    Voice Call flow (from main window with call accepted)
    ======================================================
    
    Note: Only showing participant and session state change events.

    1.  MainWndProc - User selects to make a call to a buddy / SIP URI
    2.  MainWndProc - Does some error checking, URI formatting if nessary, calls SessionWindowCallback
    3.  SessionWindowCallback - Initializes sesion window, more error checking, calls SessionTo
    4.  SessionTo   - Creates a CSession wrapper for the session, calls the CSession::OpenVoiceSession
    5.  CSession::OpenVoiceSession  - extensive error checking, makes API calls CreateSession(), AddParticipant()
    6.  RTC Event: SessionStateChange(INPROGRESS)   - AddParticipant activates the session and places the call
    7.  RTC Event: ParticipantStateChange(INPROGRESS)   - ..
    
        ( other participant (computer assumed)  )
        a.  RTC Event: SessionStateChange(INCOMING) - error checking, sets up session related info, play ring
                                                      to notify user of incoming session
        b.  RTC Event: ParticipantStateChange(INCOMING) - more error checking, call SessionWindowCallBack 
                            with incoming user info (this path will wait for callback to return)
        c.  SessionWindowCallBack   - ask user to accept / deny incoming call
            (user accepts call)
        d.  SessionWindowCallBack   - brings up session window (if not exist), return ACCEPTED to event handler
        e.  RTC Event: ParticipantStateChange(INCOMING) - call CSession::Accept()
        f.  CSession::Accept()  - error checking, makes API call Answer()
        g.  RTC Event::SessionStateChange(ANSWERING)    -   stop the ringing
        h.  RTC Event::ParticipantStateChange(ANSWERING)    - no op.
    
    (Both parties)  
        Note: at this point the call will be active so sound will be coming over the wire
    
    8,  g.  RTC Event::SessionStateChange(CONNECTED)    - no op
    9,  h.  RTC Event::ParticipantStateChange(CONNECTED)    - notify SessionWindowCallBack of connected user
    10, i.  SessionWindowCallBack   - Notify user of accepted participant via text display

User Information for use with profiles
======================================

The user's name, URI, and local phone are stored in the registry under
HKEY_CURRENT_USER\Software\Microsoft\VoipDemo
    User Data
    User Profile
        
List of Files w/ explanation
=============================

        Readme.txt              -   This File

    Common include files / data structures
    --------------------------------------
        DBase.cpp               -   Methods and functions to store buddy,presence, and my information into the CE DB
        DBase.h                 -   ..
        ht.h                    -   simple templated hash table, low load (best when < 10 objects), 
                                    currently used only in Session.cpp
        rtcs.h                  -   Internal types, function prototypes, macros, defines, and 
                                    includes used in both the RTC and the UI portions of the code
        StdAfx.cpp              -   Pre-compiled headers
        StdAfx.h                -           .
        vdtypes.cpp             -   Definitions of class functions for internal types, 
                                    specifically PARTICIPANT_INFO, LOCAL_USER_INFO, and BUDDY_TYPE

    Interface between RTC backend and UI
    --------------------------------------
        rtcs.cpp                -   Code to interface between the RTC API and the user interface.  Code
                                    for RTC initialization / shutdown, sessions, buddies, and presence.
        rtcs.h                  -   See Common include files...
    
    UI code
    --------
        VoIPDemo.cpp            -   Main program instance.  The main window procedure, app initialization /
                                    shutdown, main window child dialog procs, and listview code
        VoIPDemo.h              -   ..
        SessionWnd.cpp          -   Procs for the session window (UI / manager of IM/Voice sessions), including
                                    the sessionwindow callback function.
        SessionWnd.h            -   ..
        splashscr.cpp           -   Splashscreen to notify user that VoIPDemo.exe is starting
        splashscr.h             -   ..

    RTC backend code
    -----------------
        rtcevent.cpp            -   RTC Event handler
        rtcInternal.h           -   RTC scope globals, defines, macros, and function declarations
        rtcsetup.cpp            -   Add IIDs for the RTC COM interfaces into the Registry
        rtcsetup.h              -   ..
        Session.cpp             -   RTC Session wrapper class.  Keeps session-related code in one place
        Session.h               -   ..
        SessionContainer.cpp    -   Container class for our Session wrapper.  Allows identifying a session
                                    wrapper by an RTC handle, makes use of ht.h
        SessionContainer.h      -   ..


    Resource / UI definitions files
    ---------------------------------
        newres.h                -   resource defines
        resource.h              -   ..
        VoIPDemo.rc             -   Describes dialog boxes, bitmaps, and other resources used in the program UI             

    MIDL file for RTC COM object interfacing
    -----------------------------------------
        rtccallp.idl            -   ..

    MIDL generated source
    ----------------------
        dlldata.c               -   ..
        rtccallp.h              -   ..
        rtccallp_i.c            -   ..
        rtccallp_p.c            -   ..
        rtccall.h               -   describes the RTC types as generated from rtccallp.idl