docs: Update documentation for new dial/create_call API

- Updated __init__.py docstring with simple and advanced examples
- Updated README.md Quick Start and Call section
- Updated examples/README.md with advanced_call.py documentation

Author: moha-abdi

PySIP/__init__.py

@@ -3,7 +3,7 @@
 
 A modern, asyncio-based SIP/VoIP library for Python.
 
-Example (with context manager):
+Example (simple - context manager):
     from PySIP import SIPClient
     
     async with SIPClient(
@@ -13,13 +13,14 @@
     ) as client:
         await client.register()
         
+        # dial() returns a Call that auto-connects and auto-hangups
         async with client.dial("sip:bob@example.com") as call:
             await call.say("Hello!")
             result = await call.gather(max_digits=4, timeout=10)
             print(f"Got digits: {result.digits}")
             # Auto-hangup when exiting
 
-Example (manual control):
+Example (advanced - configure before connecting):
     from PySIP import SIPClient
     
     async with SIPClient(
@@ -29,8 +30,15 @@
     ) as client:
         await client.register()
         
-        call = client.dial("sip:bob@example.com")
-        await call.dial()  # Start the call
+        # create_call() returns unconfigured Call for advanced setup
+        call = client.create_call("sip:bob@example.com")
+        call.set_caller_id("sip:support@company.com")
+        call.set_display_name("Support Line")
+        call.add_header("X-Campaign-ID", "promo123")
+        call.set_codecs(["pcmu", "pcma"])
+        call.on("ringing", lambda: print("Ringing..."))
+        
+        await call.connect()  # Now connect
         await call.say("Hello!")
         await call.hangup()
 """

README.md

@@ -92,7 +92,7 @@ async def main():
 asyncio.run(main())
 ```
 
-### Manual Call Control
+### Advanced Call Configuration
 
 ```python
 import asyncio
@@ -106,10 +106,26 @@ async def main():
     ) as client:
         await client.register()
 
-        # Create and dial manually
-        call = client.dial("1234567890")
-        await call.dial()  # Start the call
+        # Create call and configure before connecting
+        call = client.create_call("1234567890")
 
+        # Configure call identity
+        call.set_caller_id("sip:support@company.com")
+        call.set_display_name("Support Line")
+        
+        # Add custom SIP headers
+        call.add_header("X-Campaign-ID", "promo123")
+        call.add_header("X-Account-ID", "12345")
+        
+        # Set codec preferences
+        call.set_codecs(["pcmu", "pcma"])
+        
+        # Set up event handlers
+        call.on("ringing", lambda: print("Ringing..."))
+        call.on("answered", lambda: print("Connected!"))
+        
+        # Now connect
+        await call.connect()
         await call.say("Hello!")
         await call.hangup()
 
@@ -247,9 +263,15 @@ async with client.dial("destination") as call:
     await call.say("Hello!")
     # Auto-hangup on exit
 
-# Or manual control
-call = client.dial("destination")
-await call.dial(timeout=60)
+# Advanced: Configure before connecting
+call = client.create_call("destination")
+call.set_caller_id("sip:support@company.com")   # Override From URI
+call.set_display_name("Support Line")            # Caller display name
+call.add_header("X-Campaign", "promo")           # Custom SIP headers
+call.set_codecs(["pcmu", "pcma"])                # Codec preference
+call.set_timeout(30)                             # Connection timeout
+call.on("ringing", on_ring_handler)              # Event callbacks
+await call.connect()
 
 # Media operations
 await call.say("Hello!")                        # TTS
@@ -260,13 +282,16 @@ await call.send_dtmf("1234")                    # Send DTMF
 # Call control
 await call.hold()                               # Put on hold
 await call.unhold()                             # Resume
+await call.mute()                               # Mute microphone
+await call.unmute()                             # Unmute
 await call.hangup()
 await call.transfer("other@example.com")
 
 # Properties
 call.state          # CallState enum
 call.call_id        # SIP Call-ID
 call.duration       # Call duration in seconds
+call.is_active      # True if call is active
 ```
 
 ### Error Handling

examples/README.md

@@ -56,6 +56,7 @@ python examples/basic_call.py --help
 | Script | Description |
 |--------|-------------|
 | `basic_call.py` | Simple outbound call with TTS greeting |
+| `advanced_call.py` | Advanced call with custom headers, caller ID, codecs |
 | `ivr_menu.py` | Incoming call handler with IVR menu |
 | `gather_pin.py` | DTMF collection and PIN validation |
 | `record_call.py` | Call recording to WAV file |
@@ -78,6 +79,40 @@ python examples/basic_call.py --to 1234567890 --message "Hello from PySIP!"
 python examples/basic_call.py --help
 ```
 
+### advanced_call.py - Advanced Call Configuration
+
+Demonstrates power-user features:
+- Custom caller ID and display name
+- Custom SIP headers
+- Codec preferences
+- Event callbacks (ringing, answered, hangup)
+
+```bash
+# With custom caller ID and display name
+python examples/advanced_call.py --to 123 \
+    --caller-id "sip:sales@company.com" \
+    --display-name "Sales Team"
+
+# With custom SIP headers
+python examples/advanced_call.py --to 123 \
+    --header "X-Campaign-ID:promo2024" \
+    --header "X-Account-ID:12345"
+
+# With codec preferences and timeout
+python examples/advanced_call.py --to 123 \
+    --codecs "pcmu,pcma" \
+    --timeout 45
+
+# Full example with all options
+python examples/advanced_call.py --to 123 \
+    --caller-id "sip:support@company.com" \
+    --display-name "Support Line" \
+    --header "X-Priority:high" \
+    --codecs "pcmu" \
+    --timeout 30 \
+    --user-agent "MyApp/1.0"
+```
+
 ### ivr_menu.py - IVR Menu Server
 
 Registers with the SIP server and handles incoming calls with an interactive menu: