0
# PyObjC Framework MultipeerConnectivity
1

2
Python wrappers for the macOS MultipeerConnectivity framework enabling peer-to-peer networking, device discovery, and data exchange between nearby devices over Wi-Fi, Bluetooth, and infrastructure networks without requiring internet connectivity.
3

4
## Package Information
5

6
- **Package Name**: pyobjc-framework-MultipeerConnectivity
7
- **Language**: Python with C extensions
8
- **Installation**: `pip install pyobjc-framework-MultipeerConnectivity`
9
- **Dependencies**: `pyobjc-core>=10.3.2`, `pyobjc-framework-Cocoa>=10.3.2`
10
- **Platform**: macOS 10.10+ only
11
- **Minimum OS**: macOS 10.10 (Yosemite)
12

13
## Core Imports
14

15
```python
16
import MultipeerConnectivity
17
```
18

19
Access to specific classes:
20

21
```python
22
from MultipeerConnectivity import (
23
    MCPeerID, MCSession, MCNearbyServiceAdvertiser, MCNearbyServiceBrowser,
24
    MCAdvertiserAssistant, MCBrowserViewController
25
)
26
```
27

28
## Basic Usage
29

30
```python
31
import MultipeerConnectivity
32
from Foundation import NSData, NSString
33

34
# Create a peer ID to identify this device
35
peer_id = MultipeerConnectivity.MCPeerID.alloc().initWithDisplayName_("MyDevice")
36

37
# Create a session for peer-to-peer communication
38
session = MultipeerConnectivity.MCSession.alloc().initWithPeer_(peer_id)
39

40
# Start advertising this device as available for connection
41
service_type = "my-app-service"
42
advertiser = MultipeerConnectivity.MCNearbyServiceAdvertiser.alloc().initWithPeer_discoveryInfo_serviceType_(
43
    peer_id, None, service_type
44
)
45

46
# Start browsing for other peers
47
browser = MultipeerConnectivity.MCNearbyServiceBrowser.alloc().initWithPeer_serviceType_(
48
    peer_id, service_type
49
)
50

51
# Send data to connected peers
52
message = "Hello from Python!"
53
data = message.encode('utf-8')
54
nsdata = NSData.alloc().initWithBytes_length_(data, len(data))
55

56
connected_peers = session.connectedPeers()
57
if connected_peers:
58
    success = session.sendData_toPeers_withMode_error_(
59
        nsdata, 
60
        connected_peers, 
61
        MultipeerConnectivity.MCSessionSendDataReliable,
62
        None
63
    )
64
```
65

66
## Architecture
67

68
MultipeerConnectivity provides a framework for establishing peer-to-peer networks between devices:
69

70
- **Peer Discovery**: Automatic discovery of nearby devices using Bonjour over Wi-Fi and Bluetooth
71
- **Session Management**: Reliable connection establishment and maintenance between peers
72
- **Data Transport**: Support for reliable and unreliable data transmission modes
73
- **Security**: Optional encryption and certificate validation for secure communications
74
- **UI Components**: Ready-to-use view controllers for peer browsing and connection management
75

76
The framework abstracts the underlying network transport (Wi-Fi, Bluetooth, or infrastructure) and provides a unified API for peer-to-peer communication.
77

78
## Capabilities
79

80
### Peer Identification
81

82
Represents and manages peer identity in the multipeer connectivity network.
83

84
```python { .api }
85
class MCPeerID:
86
    def initWithDisplayName_(self, displayName: str) -> MCPeerID: ...
87
    def displayName(self) -> str: ...
88
    def hash(self) -> int: ...
89
    def isEqual_(self, object: object) -> bool: ...
90
```
91

92
### Session Management
93

94
Manages peer-to-peer communication sessions with connection state tracking and data transmission.
95

96
```python { .api }
97
class MCSession:
98
    def initWithPeer_(self, myPeerID: MCPeerID) -> MCSession: ...
99
    def initWithPeer_securityIdentity_encryptionPreference_(
100
        self, myPeerID: MCPeerID, 
101
        identity: object, 
102
        encryptionPreference: int
103
    ) -> MCSession: ...
104
    
105
    def sendData_toPeers_withMode_error_(
106
        self, data: NSData, 
107
        peerIDs: list, 
108
        mode: int, 
109
        error: object
110
    ) -> bool: ...
111
    
112
    def disconnect(self) -> None: ...
113
    def connectedPeers(self) -> list: ...
114
    def myPeerID(self) -> MCPeerID: ...
115
    
116
    def sendResourceAtURL_withName_toPeer_withCompletionHandler_(
117
        self, resourceURL: NSURL,
118
        resourceName: str,
119
        peerID: MCPeerID, 
120
        completionHandler: callable
121
    ) -> object: ...
122
    
123
    def startStreamWithName_toPeer_error_(
124
        self, streamName: str,
125
        peerID: MCPeerID,
126
        error: object
127
    ) -> NSOutputStream: ...
128
    
129
    def nearbyConnectionDataForPeer_withCompletionHandler_(
130
        self, peerID: MCPeerID,
131
        completionHandler: callable
132
    ) -> None: ...
133
```
134

135
### Service Advertising
136

137
Advertises the local peer's availability to nearby devices for connection requests.
138

139
```python { .api }
140
class MCNearbyServiceAdvertiser:
141
    def initWithPeer_discoveryInfo_serviceType_(
142
        self, myPeerID: MCPeerID,
143
        info: dict,
144
        serviceType: str
145
    ) -> MCNearbyServiceAdvertiser: ...
146
    
147
    def startAdvertisingPeer(self) -> None: ...
148
    def stopAdvertisingPeer(self) -> None: ...
149
    def delegate(self) -> object: ...
150
    def setDelegate_(self, delegate: object) -> None: ...
151
    def myPeerID(self) -> MCPeerID: ...
152
    def discoveryInfo(self) -> dict: ...
153
    def serviceType(self) -> str: ...
154
```
155

156
### Service Discovery
157

158
Discovers and browses for nearby peers advertising compatible services.
159

160
```python { .api }
161
class MCNearbyServiceBrowser:
162
    def initWithPeer_serviceType_(
163
        self, myPeerID: MCPeerID,
164
        serviceType: str
165
    ) -> MCNearbyServiceBrowser: ...
166
    
167
    def startBrowsingForPeers(self) -> None: ...
168
    def stopBrowsingForPeers(self) -> None: ...
169
    def invitePeer_toSession_withContext_timeout_(
170
        self, peerID: MCPeerID,
171
        session: MCSession,
172
        context: NSData,
173
        timeout: float
174
    ) -> None: ...
175
    def delegate(self) -> object: ...
176
    def setDelegate_(self, delegate: object) -> None: ...
177
    def myPeerID(self) -> MCPeerID: ...
178
    def serviceType(self) -> str: ...
179
```
180

181
### High-Level Advertising Helper
182

183
Simplified interface for advertising peer availability with minimal configuration.
184

185
```python { .api }
186
class MCAdvertiserAssistant:
187
    def initWithServiceType_discoveryInfo_session_(
188
        self, serviceType: str,
189
        info: dict,
190
        session: MCSession
191
    ) -> MCAdvertiserAssistant: ...
192
    
193
    def start(self) -> None: ...
194
    def stop(self) -> None: ...
195
    def delegate(self) -> object: ...
196
    def setDelegate_(self, delegate: object) -> None: ...
197
    def session(self) -> MCSession: ...
198
    def discoveryInfo(self) -> dict: ...
199
    def serviceType(self) -> str: ...
200
```
201

202
### Peer Browser UI
203

204
Pre-built user interface for discovering and connecting to nearby peers.
205

206
```python { .api }
207
class MCBrowserViewController:
208
    def initWithServiceType_session_(
209
        self, serviceType: str,
210
        session: MCSession
211
    ) -> MCBrowserViewController: ...
212
    
213
    def initWithBrowser_session_(
214
        self, browser: MCNearbyServiceBrowser,
215
        session: MCSession
216
    ) -> MCBrowserViewController: ...
217
    
218
    def delegate(self) -> object: ...
219
    def setDelegate_(self, delegate: object) -> None: ...
220
    def browser(self) -> MCNearbyServiceBrowser: ...
221
    def session(self) -> MCSession: ...
222
    def minimumNumberOfPeers(self) -> int: ...
223
    def setMinimumNumberOfPeers_(self, minimumNumberOfPeers: int) -> None: ...
224
    def maximumNumberOfPeers(self) -> int: ...
225
    def setMaximumNumberOfPeers_(self, maximumNumberOfPeers: int) -> None: ...
226
```
227

228
## Constants and Enums
229

230
### Session Send Data Modes
231

232
```python { .api }
233
MCSessionSendDataReliable: int = 0     # Guaranteed delivery, ordered
234
MCSessionSendDataUnreliable: int = 1   # Best effort delivery, unordered
235
```
236

237
### Session States
238

239
```python { .api }
240
MCSessionStateNotConnected: int = 0    # Peer is not connected
241
MCSessionStateConnecting: int = 1      # Peer is connecting
242
MCSessionStateConnected: int = 2       # Peer is connected
243
```
244

245
### Encryption Preferences
246

247
```python { .api }
248
MCEncryptionOptional: int = 0          # Encryption preferred but not required
249
MCEncryptionRequired: int = 1          # Encryption required for connection
250
MCEncryptionNone: int = 2              # No encryption
251
```
252

253
### Session Limits
254

255
```python { .api }
256
kMCSessionMinimumNumberOfPeers: int    # Minimum peers in session (typically 1)
257
kMCSessionMaximumNumberOfPeers: int    # Maximum peers in session (typically 8)
258
```
259

260
### Error Codes
261

262
```python { .api }
263
MCErrorDomain: str                     # Error domain identifier
264

265
MCErrorUnknown: int = 0                # Unknown error
266
MCErrorNotConnected: int = 1           # Peer not connected
267
MCErrorInvalidParameter: int = 2       # Invalid parameter passed
268
MCErrorUnsupported: int = 3            # Operation not supported
269
MCErrorTimedOut: int = 4               # Operation timed out
270
MCErrorCancelled: int = 5              # Operation was cancelled
271
MCErrorUnavailable: int = 6            # Service unavailable
272
```
273

274
## Delegate Protocols
275

276
### MCSessionDelegate
277

278
```python { .api }
279
# Required methods
280
def session_peer_didChangeState_(self, session: MCSession, peerID: MCPeerID, state: int) -> None:
281
    """Called when a peer changes connection state"""
282

283
def session_didReceiveData_fromPeer_(self, session: MCSession, data: NSData, peerID: MCPeerID) -> None:
284
    """Called when data is received from a peer"""
285

286
def session_didReceiveStream_withName_fromPeer_(
287
    self, session: MCSession, stream: NSInputStream, streamName: str, peerID: MCPeerID
288
) -> None:
289
    """Called when a stream is received from a peer"""
290

291
def session_didStartReceivingResourceWithName_fromPeer_withProgress_(
292
    self, session: MCSession, resourceName: str, peerID: MCPeerID, progress: NSProgress
293
) -> None:
294
    """Called when starting to receive a resource from a peer"""
295

296
def session_didFinishReceivingResourceWithName_fromPeer_atURL_withError_(
297
    self, session: MCSession, resourceName: str, peerID: MCPeerID, localURL: NSURL, error: NSError
298
) -> None:
299
    """Called when finished receiving a resource from a peer"""
300

301
# Optional methods
302
def session_didReceiveCertificate_fromPeer_certificateHandler_(
303
    self, session: MCSession, certificate: NSArray, peerID: MCPeerID, certificateHandler: callable
304
) -> None:
305
    """Called to validate peer certificate for secure connections"""
306
```
307

308
### MCNearbyServiceAdvertiserDelegate
309

310
```python { .api }
311
# Required method
312
def advertiser_didReceiveInvitationFromPeer_withContext_invitationHandler_(
313
    self, advertiser: MCNearbyServiceAdvertiser, 
314
    peerID: MCPeerID, 
315
    context: NSData, 
316
    invitationHandler: callable
317
) -> None:
318
    """Called when receiving an invitation from a peer"""
319

320
# Optional method
321
def advertiser_didNotStartAdvertisingPeer_(
322
    self, advertiser: MCNearbyServiceAdvertiser, 
323
    error: NSError
324
) -> None:
325
    """Called when advertising fails to start"""
326
```
327

328
### MCNearbyServiceBrowserDelegate
329

330
```python { .api }
331
# Required methods
332
def browser_foundPeer_withDiscoveryInfo_(
333
    self, browser: MCNearbyServiceBrowser, 
334
    peerID: MCPeerID, 
335
    info: dict
336
) -> None:
337
    """Called when a peer is discovered"""
338

339
def browser_lostPeer_(
340
    self, browser: MCNearbyServiceBrowser, 
341
    peerID: MCPeerID
342
) -> None:
343
    """Called when a peer is lost"""
344

345
# Optional method
346
def browser_didNotStartBrowsingForPeers_(
347
    self, browser: MCNearbyServiceBrowser, 
348
    error: NSError
349
) -> None:
350
    """Called when browsing fails to start"""
351
```
352

353
### MCBrowserViewControllerDelegate
354

355
```python { .api }
356
# Required methods
357
def browserViewControllerDidFinish_(self, browserViewController: MCBrowserViewController) -> None:
358
    """Called when user finishes with browser"""
359

360
def browserViewControllerWasCancelled_(self, browserViewController: MCBrowserViewController) -> None:
361
    """Called when user cancels browser"""
362

363
# Optional method
364
def browserViewController_shouldPresentNearbyPeer_withDiscoveryInfo_(
365
    self, browserViewController: MCBrowserViewController,
366
    peerID: MCPeerID,
367
    info: dict
368
) -> bool:
369
    """Called to determine if peer should be shown in browser"""
370
```
371

372
### MCAdvertiserAssistantDelegate
373

374
```python { .api }
375
# Optional methods
376
def advertiserAssistantWillPresentInvitation_(
377
    self, advertiserAssistant: MCAdvertiserAssistant
378
) -> None:
379
    """Called before presenting invitation dialog"""
380

381
def advertiserAssistantDidDismissInvitation_(
382
    self, advertiserAssistant: MCAdvertiserAssistant  
383
) -> None:
384
    """Called after dismissing invitation dialog"""
385
```
386

387
## Types
388

389
### Foundation Types
390

391
```python { .api }
392
NSData = object          # Binary data container
393
NSString = object        # String object  
394
NSURL = object           # URL reference
395
NSInputStream = object   # Input stream
396
NSOutputStream = object  # Output stream
397
NSProgress = object      # Progress reporting
398
NSError = object         # Error information
399
NSArray = object         # Array container
400
```